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Preface 


SEC XSR POG-001 


This Document is a Porting Guide for XSR (eXtended Sector Remapper) developed by 
Samsung Electronics. 


Purpose 


This document is XSR Porting Guide. This document explains the definition, architecture, 
system requirement, and porting tutorial of XSR. This document also provides the features 


and API of each module - OAM, PAM, LLD - that a user should know well to port XSR. 


Scope 


This document is for Project Manager, Project Leader, Application Programmers, etc. 


Definitions and Acronyms 


FTL (Flash Translation A software module which maps between logical addresses and 
Layer) physical addresses when accessing to flash memory 

XSR eXtended Sector Remapper 

STL Sector Translation Layer 

BML Block Management Layer 

LLD Low Level Device Driver 

Initial bad block Invalid blocks upon arrival from the manufacturers 


Run-time bad block 


Additional invalid blocks may occur during the life of NAND 
flash usage 


Sector The file system performs read/write operations in a 512-byte 
unit called sector. 

Page NAND flash memory is partitioned into fixed-sized pages. A 
page is (512+16) bytes or (2048 + 64) bytes. 

Block NAND flash memory is partitioned into fixed-sized blocks. A 


Wear-Leveling 


block is 16K bytes or 128K bytes. 
Wear-leveling algorithm is an algorithm for increasing lifetime 


algorithm of NAND flash memory 

NAND flash device NAND flash device is a device that contains NAND flash 
memory or NAND flash controller. 

NAND flash memory NAND-type flash memory 

Deferred Check The method that can increase time and device operation 

Operation performance. Every operation function of LLD defers the 
check routine to the next operation. 

OneNAND Samsung NAND flash device that includes NAND flash 


memory and NAND flash controller. 


Related Documents 


- SEC, XSR v1.5.1 Part 1. Sector Translation Layer Programmer’s Guide, Samsung 
Electronics, Co., LTD, APR-07-2006 
- SEC, XSR v1.5.1 Part 2. Block Management Layer Programmer’s Guide, Samsung 
Electronics, Co., LTD, APR-07-2006 


XSR v1.5.1 Porting Guide 3 


SAMSUNG OMT 


History 
Version | Date Comment Author Approval 
0.1 JULY-05-2004 | Initial version Seungeun Lee 
Updated version 
- Delete FIL ; Some of FIL 
functionalities is shifted to 
BML or LLD. 
- Add a synchronous feature 
- Add chapater 7.5. “Byte 
Alignment Restriction” 
0.2 JULY-09-2004 ode MEesdMWEt Seungeun Lee 
function 
- Modify the figure of XSR 
system architecture. 
XSR consists of XSR Core 
(STL and BML), OAM, 
PAM, and LLD. In the 
previous verion, XSR_ has 
only STL and BML 
1.0 JULY-09-2004 | Released version Seungeun Lee ee 
Updated version Min Young 
- Add MErase/ EraseVerify | Kim 
ee Soren function Se Wook Na 
- Add ECC Policy Seungeun Lee 
2.0 OCT-19-2004 | Released version Seungeun Lee Nga 
Updated version 
- Add PAM interrupt | Min Young 
functions Kim 
es NON | Modify OAM _ interrupt | Se Wook Na 
functions and timer functions | Seungeun Lee 
- Modify Interrupt and Timer 
3.0 DEC-09-2004 | XSR v1.3.1 Release Seungeun Lee oe 
Min Young 
3.1 JAN-14-2005 | Modify ECC Poli ae 
, we aad ie Se Wook Na 
Seungeun Lee 
Updated version for XSR 
v1.4.0 Min Young Song fie 
4.0 JUN-24-2005 | - Add PAM_Memcpy Kim Yoon 
- Modify ECC policy Se Wook Na 
- Modify interrupt and timer 
5.0 RCS | FEB-20-2006 | XSR v1.5.0 RCS Release Byoune 
Young Ahn 
5A APR-07-2006 | XSR v1.5.1 Release a 
Young Ahn 


XSR v1.5.1 Porting Guide 4 


SAMSUNG OMT 


Contents 
1. Introduction 9 
1.1. XSR Overview 9 
1.2. XSR System Architecture 10 
1.3. XSR Features 11 
2. Development Environment 12 
2.1. System Requirement 12 
2.2. Directory Structure 12 
3. Porting Tutorial 14 
3.1. Prerequisite 14 
3.1.1. Porting Outline 14 
3.1.2. Condition Check 15 
3.2. Porting Example 16 
3.2.1. Extract XSR File 16 
3.2.2. OAM Porting 16 
3.2.3. LLD Porting 22 
3.2.4. PAM Porting 34 
3.2.5. Application Creating 37 
4. OAM (OS Adaptation Module 44 
4.1. Description & Architecture 44 
4.2. API 46 
OAM_Malloc 47 
OAM_Free 48 
OAM_Memcpy 49 
OAM_Memset 51 
OAM_Memcmp 52 
OAM_Debug 54 
OAM_CreateSM 55 
OAM_DestroySM 57 
OAM_AcquireSM 59 
OAM_ReleaseSM 61 
OAM_InitInt 63 
OAM_BindInt 65 
OAM_EnableInt 67 
OAM_DisableInt 69 
OAM_ClearInt 71 
OAM _ResetTimer 73 
OAM_GetTime 75 
OAM_WaitNMSec 77 
OAM_Pa2Va 78 
5. LLD (Low Level Driver 82 
5.1. Description & Architecture 82 
5.2. API 84 
XXX_Init 85 
XXX_Open 87 
XXX_Close 90 
XXX_GetDevInfo 92 
XSR v1.5.1 Porting Guide 5 


SAMSUNG DeGIT 


i 
Pena sb liviled 


XXX_Read 97 
XXX_Write 102 
XXX_Erase 107 
XXX_MRead 110 
XXX_MWrite 118 
XXX_MErase 126 
XXX_EraseVerify 132 
XXX_CopyBack 135 
XXX_ChkInitBadBlk 143 
XXX_SetRWArea 145 
XXX_IOC# 147 
XXX_GetPrevOpData 153 
XXX_FlushOp 156 
6. PAM (Platform Adaptation Module 158 
6.1. Description & Architecture 158 
6.2. API 160 
PAM_Init 161 
PAM_GetPAParm 162 
PAM_RegLFT 166 
PAM_InitInt 170 
PAM_BindInt 172 
PAM_EnableInt 174 
PAM_DisableInt 176 
PAM_ClearInt 178 
PAM_Memcpy 180 

7. Advanced Topics 182 
7.1. Semaphore 182 
7.1.1. Backgrounds 182 
7.1.2. Semaphore 183 
7.1.3. Implementation 184 
7.2. Interrupt 188 
7.2.1. Interrupt of Device Driver Concept 188 
7.2.2. Synchronous / Asynchronous Device Driver Model 189 
7.2.3. BML and Interrupt 192 
7.2.4. STL and Interrupt 192 
7.2.5. Timer 195 
7.2.6. Implementation 197 
7.3. Power-Off Recovery 200 
7.3.1. Power-Off Error Processing and Timer 200 
7.3.2. Implementation 203 
7.4. Deferred Check Operation 204 
7.5. Byte Alignment Restrictions 206 
7.6. ECC Policy 209 
Appendix 217 
I. OAM.h 217 
Il. LLD.h 219 
I. PAM.h 223 
Index 225 


XSR v1.5.1 Porting Guide 6 


SAMSUNG ONGIT. 


i 
Pena eb liviled 


Figures 


Figure 1-1. 
Figure 2-1. 
Figure 3-1. 
Figure 3-2. 
Figure 3-3. 
Figure 3-4. 
Figure 3-5. 
Figure 3-6. 
Figure 3-7. 
Figure 3-8. 
Figure 3-9. 
Figure 4-1. 
Figure 5-1. 
Figure 6-1. 
Figure 6-2. 
Figure 6-3. 
Figure 7-1. 
Figure 7-2. 
Figure 7-3. 
Figure 7-4. 
Figure 7-5. 
Figure 7-6. 
Figure 7-7. 
Figure 7-8. 
Figure 7-9. 


Figure 7-10. 
Figure 7-11. 
Figure 7-12. 
Figure 7-13. 
Figure 7-14. 
Figure 7-15. 
Figure 7-16. 
Figure 7-17. 
Figure 7-18. 
Figure 7-19. 


XSR System Architecture 

XSR and Platform Directory Structure 
XSR Porting Flowchart 

XSR and Platform Directory 

XSR and Platform Directory 

OAM Function Classification 

Simple NAND Emulator Design 

LLD Function Classification 

PAM Function Classification 
XSRHello Project Structure 
XSRHello Project Working Screen 
OAM in XSR System Architecture 
LLD in XSR System Architecture 
PAM in XSR System Architecture 
Register LLD Address to BML 
Define Volume and Device of BML 
Simultaneous Requests to BML 
Semaphore Operation in BML 
Semaphore Usage Example 

Device Driver Concept 

Interrupt of Hardware Device 

Polling 

Synchronous Device Driver Operation 
Interrupt Usage at Device Driver 
Asynchronous Device Driver Operation 
BML and Interrupt 

STL to BML Mapping Example 


STL_Sync() Operation (nQuantum: 1) 
Flowchart of STL_Sync(Q) 


Power-off Slope Assumption 
NAND Block Erase Error at Power-off 
OAM_WaitNMSec() Usage 


Operation Queue Created by STL_AWrite() 


Flow between upper layer and XSR in asynchronous mode 


Compare General Operation with Deferred Check Operation 


XSR v1.5.1 Porting Guide 


7 


SAMSUNG OVGIT. 


i 
Pena eb laviled 


Tables 
Table 2-1. System Requirement 12 
Table 2-2. Component of XSR and Platform Directory 12 
Table 4-1. OAM API 46 
Table 5-1. LLD API 84 
Table 5-2. LLDSpec in LLD.h 93 
Table 5-3. LLDMEArg data structure in LLD.h 127 
Table 5-4. LLDMEList data structure in LLD.h 127 
Table 5-5. RndInArg data structure in XsrTypes.h 136 
Table 5-6. CpBkArg data structure in XsrTypes.h 136 
Table 6-1. PAM API 160 
Table 7-1. XSR Multiple volume/device supporting 183 
Table 7-2. 4Byte Alignment Example 206 
Table 7-3. Usage of Main Buffer and Spare Buffer in Read/Write Operation 210 
Table 7-4. Return values of Main area ECC error 211 
Table 7-5. Return values of Spare area ECC error 211 


XSR v1.5.1 Porting Guide 8 


SAMSUNG D0GM Tai! 


aver pee a liviled 


1. Introduction 


This document is a Porting Guide of XSR (eXtended Sector Remapper). This chapter first 
introduces the definition, system architecture, and features of XSR. 


1.1. XSR Overview 


0 Flash Memory 


Flash memory is an electronically programmable nonvolatile memory. It is used in laptop 
computer, PDA, or cell phone as storage. It is divided into two types, NOR and NAND, 
according to its cell composition at manufacturing. NAND flash memory has higher 
capacity and is cheaper than NOR flash memory. It has many benefits and widely used as 
storage of portable device. 


XO NAND Flash Memory 


Unlike a hard disk, a user cannot rewrite data on NAND flash memory. It means user 
cannot overwrite existing data on it without first executing an erase operation. A user needs 
to erase the current data to write new data. Additionally, erase operation is performed by a 
block, which is larger than other operation unit; read and write operation is performed by a 
page on NAND flash memory. This prolongs working time, because unrelated data must 
also be erased and then rewritten to complete updating. 


NAND flash memory is also limited in the number of times it can be written to and then 
erased (erase cycles). Flash device writes data sporadically, not in its address order. Specific 
sector can be written more frequently and the entire flash device becomes unusable 
eventually. Lastly, NAND flash memory can have an initial bad block' when it is 
manufactured and a run time bad block or bit-flipping” when it is used. 


CX XSR development background 


As the above reason, a user cannot manage data on NAND flash memory like block 
devices*. Therefore, data management of NAND flash memory is very important issue. To 
cover that, Samsung Electronics develops the flash management software XSR (eXtended 
Sector Remapper) to use NAND flash memory as a regular block device. XSR has same 
functionalities with well-known FTL (Flash Translation Layer). Basically, it is a software 
layer or device driver, that resides between the OS file system and the NAND flash memory. 
XSR can be used separately and is independent of Operating system as a common 
component itself. It provides the OS with full block-device functionality so that NAND 
flash memory appears to the OS as a regular hard disk drive, while it transparently manages 
the flash data. 


' Bad block is a block on which data cannot be read, written, or erased. There are two types of bad blocks: 
Initial bad block and Run-time bad block. Initial bad block occurs from manufacturer and runtime bad block 
occurs during using of NAND flash memory. 

? Bad block is a block on which data cannot be read, written, or erased. When 1 bit error happens, XSR corrects 
the error itself, called bit-flipping. 

3 Block devices include all disk drives and other mass-storage devices on the computer. 
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1.2. XSR System Architecture 


As mentioned in chapter 1.1. XSR Overview, XSR exists between the file system and 
NAND flash memory. It works in conjunction with an existing Operating system or in some 
embedded applications. 


Figure 1-1 shows the system architecture of XSR. 


POMOC eee ree ee eee ee reece eee ee eee e eee eee ee eee CeO EEO ESET OEE SDSL EET O SOS D OLE S ESTOS EOE O STOTT SESE OTC E EOE LO OES O OSD E LOOT OSES TEE E STOEL OTT EES * 


File System 
| 


Block Device Interface 


Logical Flash Address 


XSR Core 


Sector Translation Layer 


Virtual Flash Address 


OS Adaptation 
Module 


Platform Adaptation 
Module 


Block Management Layer 


Physical Flash Address 


Low Level Device Driver 


NAND Flash Memory 


Figure 1-1. XSR System Architecture 


There is a file system at the top of the figure. Block device interface exists between the file 
system and XSR. Block device interface is a kind of driver layer, which provides a file 
system with block device services. Block device interface code is ported for each OS. 


There is XSR at the middle of the figure and it consists of four parts: XSR core, OAM (OS 
Adaptation Module, PAM (platform adaptation module), and LLD (Low Level Device 
Driver). The following briefly explains each of them. 


O XSR core: XSR core is composed of two layers: STL (Sector Translation Layer) and 


BML (Block Management Layer). STL is a top layer of XSR. BML is below the STL. The 
layers specifically have different features with each other, but all they are to perform the 
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basic functionalities of XSR as block device emulation and flash memory management. The 
main features of each layer are as follows. 


- STL (Sector Translation Layer): translates a logical address from the file system into 
the virtual flash address. It internally has wear-leveling* during the address 
translation. 


- BML (Block Management Layer): translates the virtual address from the upper layer 
into the physical address. At this time, BML does the address translation in 
consideration of bad block and the number of NAND device in use. BML accesses 
LLD®, which actually performs read, write, or erase operation, with the physical 
address. 


Note 


Each layer of XSR can be operated separately as a module. Thus, STL can be used with 
other layer, which has same functionalities with BML. 


O OAM: OAM is at the right of the figure. OAM connects XSR with the OS. OAM needs 
to be configured according to your OS environment to use NAND flash memory. 


OO PAM: PAM is below OAM. PAM connects XSR with the platform. PAM also needs to 
be configured according to your platform to use NAND flash memory. 


O LLD: There is a low level device driver between BML and NAND flash memory. It 
reads, writes, or erases data on the physical sector address received from XSR and is 
controlled by BML. 


1.3. XSR Features 


The following describes the main benefits and features of XSR implementation. 


O It emulates a block device and manages data on NAND flash memory efficiently. 

O It extends the life span of NAND flash memory by enhancing Wear- leveling. 

0 It can be embedded in any kind of OS using NAND flash memory. 

CO It enhances data integrity by managing a bad block and performing error detection or 
correction. 

O It reduces data loss in case of sudden power failure with the advanced algorithms, and 
guarantees data stability. 


In the next chapter, XSR build and installation procedures are covered in detail. 


* Wear-leveling is an internal operation to use every block of NAND flash memory evenly through the 
algorithm. It extends NAND flash memory life span. 

° LLD is an abbreviation of Low Level Device Driver. It performs actual read/write/erase operation to NAND 
flash memory as a device driver. 
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2. Development Environment 


This chapter describes the system requirement and the directory structure. 


2.1. System Requirement 


Table 2-1 shows the system requirement to install XSR and use it. 


Table 2-1. System Requirement 


System Requirement 

Host OS Windows 2K/XP 

Target CPU 50 mips 

Source Disk Space About 8 MB 

NAND Flash Chip Samsung NAND Chip Emulator using RAM 
Target Disk Space Minimum 50 MB 


2.2. Directory Structure 


Figure 2-1 shows the XSR and Platform Directory Structure. Depending on type of released 
package, detail structure of directories can be different from Figure 2-1. 


= Platform 
# Gy PAM 
= Xs 

> Core 
& Inc 
& Lib 
& LLD 
(3 OAM 
G& UTIL 


Figure 2-1. XSR and Platform Directory Structure 


(+) 


&) &) & 


Table 2-2 describes the components of XSR and Platform directory structure in Figure 2-1. 
The following table only refers to porting related components of XSR and Platform 
directory. 


Table 2-2. Component of XSR and Platform Directory 


Directory Description 


XSR This folder is a base directory when XSR is installed. 


Core | This folder has XSR source code. (STL and BML) 
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Inc This folder has XSR header files. 


Lib This folder has XSR libraries (STL and BML). 


LLD This folder has LLD source code. 


OAM This folder has OAM source code. 


Platform This folder is a base directory for platform dependent code. 


PAM | This folder has platform source code. 
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3. Porting Tutorial 


This chapter describes a porting example of XSR. First of all, you should read the 
prerequisite and check points. Then, follow the steps of the porting example. 


3.1. Prerequisite 


3.1.1. Porting Outline 


The procedure of the porting example is as follows. 


Extract 
XSR File 


oan 


Application 


DB Ported in porti 
: in porting example 


0 Wot ported in porting example 


Figure 3-1. XSR Porting Flowchart 
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This document shows you the process to port XSR on a PC. So, you port OAM(OS 
Adaptation Module) to Win32. You implement ANSI functions, and Message print 
functions. You do not implement the semaphore functions, because you use the single 
process. Also, you do not implement both interrupt functions and timer functions, because 
you do not use real NAND flash memory. 


In porting LLD, you do not use a real device or NAND flash memory. This document 
shows you the process to make a simple NAND emulator including small block NAND 
flash memory functionality. You do not implement functions related to Deferred Check 
Operation. 


In porting PAM, you use the simple NAND emulator that is made in implementing LLD. 
You implement the device and driver configuration functions 


After implementing OAM, LLD and PAM, you create the application in Visual Studio and 
check that XSR is normally operated. Therefore, XSR porting example will be completed. 


. Condition Check 


Before you start the porting example, you should check the files to use in porting. The 
following figure shows XSR and Platform directory structure to check. 


=) Platform 


(+) 
C 
Ee 


GE LLD 
# OAM 
BG UTIL 


Figure 3-2. XSR and Platform Directory 


The following description only refers to porting related files in XSR and Platform directory. 


0 In PAM folder, there is a template file in Template folder: MyPAM.cpp 

QO In Ine folder, there are XSR library files: BML.h, LLD.h, OAM.h, PAM.h, STL.h, 
XSR.h, and XsrTypes.h. 

O In Lib folder, there is a XSR library file in Generic\VS60\Retail folder: XsrEmul.lib. 

O In LLD folder, there are template files in Template folder: MyLLD.h and MyLLD.cpp. 
OO In OAM folder, there is a template file in Template folder: MyOAM.cpp. 


Now, you fulfill all prerequisite for the porting example. 
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Porting Example 


Follow the next porting example step by step. 


Extract XSR File 
At first, extract the provided XSR file. 


Create a folder named as XSR_ in any location to port. 


Extract XSR_1.5.1_RTM.zip or XSR_1.5.1_xxx.zip ina newly created folder 


XSR. 
Then, you can see the directory structure as follows. 


= (> Platform 
Gy PAM 
= XS 

# (> Core 
© Inc 
Es Lib 
@ G LLD 
® G OAM 
# (> UTIL 


Figure 3-3. XSR and Platform Directory 


3.2.2. OAM Porting 


Among three modules (OAM, LLD, and PAM), you port OAM at first. 


OAM, an OS-dependent module, links XSR to OS. In this porting example, you exercise 
OAM porting to Win32 because you port XSR on a PC. 


In \XSR\OAM folder, there is a template file MyOAM.cpp in Template folder. This 
template file contains 21 functions that are classified into 6 categories as follows. 
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ANS! functions : OAM Malloc, OAM Free, OAM Memepy, 
OAM Memsel, OAM Mememp 


| Message Prini function : OAM Debug 


Semaphore functions : OAM CreateSM, OAM _DesiroySM, 
OAM AcquireSM, OAM Releases 


Interrupt functions: OAM Initint, OAM Bindint,OAM Enableint 


OAM 
| OAM_Disableini, OAM_Clearint 


Timer functions ; OAM _ReseiTimer, OAM_GeiTime, 
OAM_WalNMSec 


Other functions : OAM_Pa2Va, OAM_Idle, 
OAM_GetROLockFlag 


Figure 3-4. OAM Function Classification 


The following explains the classification of OAM functions. 


XO ANSI functions 
ANSI functions are the mandatory functions that XSR library uses. You must implement 
these functions at all times. 

OAM _Malloc() 

OAM_Free () 

OAM_Memcpy () 

OAM_Memset () 

OAM _Memcmp () 


0 Message print function 
Message print function is the functions to print all XSR messages, including an error or 
debug message. If you do not implement this function, you cannot see XSR debug 
messages. 

OAM_Debug () 


CX Semaphore functions 
The semaphore functions are the functions to protect codes or devices using XSR in 
multi-task or multi-process environment. For more information about the semaphore 
functions, refer to Chapter 7.1. Semaphore. 

OAM_CreateSM () 

OAM_DestroySM () 

OAM _AcquireSM() 

OAM _ ReleaseSM () 


CO Interrupt functions 
The interrupt functions are the functions for Asynchronous functionality of XSR. For more 
information about the interrupt, refer to Chapter 7.2. Interrupt. 

OAM_InitInt () 

OAM_BindInt () 

OAM_EnableInt () 
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OAM_DisableInt () 
OAM_CleartInt () 


C1 Timer functions 
Timer functions are the functions to check the time flow for Asynchronous functionality of 
XSR or handle the time-related errors. For more information about timer, refer to Chapter 
7.2.5 Timer and 7.3 Power-Off Recovery 

OAM Reset Timer () 

OAM_GetTime () 

OAM_WaitNMSec () 


CO Other functions 

These functions does not correspond to any category above. 
OAM_Pa2Va () 
OAM Idle () 
OAM _GetROLockFlag () 


Now, port OAM to Win32. 

Make a duplicate of the existing Template folder in \XSR\OAM, and name the new folder 
as MyOAM. 

Check there is a file MyOAM.cpp in the newly named folder MyOAM. 


Open the existing file MyOAM.cpp in an editor. 


Add the followings to include the header files. 


_#include <windows.h> 
i #include <stdio.h> 

| #include <stdarg.h> 
i #include <string.h> 


Add the following code in bold to implement ANSI functions. 


| VOID * 
| OAM_Malloc(UINT32 nSize) 
a 


return malloc (nSize); 


| VOID 
| OAM_Free (VOID *pMem) 
| { 


free (pMem) ; 


| VOID 
| OAM_Memcpy (VOID *pDst, VOID *pSrc, UINT32 nLen) 
if 


memcpy ((void *) pDst, (void *) pSrc, nlLen); 
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| VOID 

| OAM_Memset (VOID *pDst, UINT8 nData, UINT32 nlen) 
| { 
i memset ((void *) pDst, (int) nData, nLen); 


| INT32 

| OAM_Mememp (VOID *pCmpl1, VOID *pCmp2, UINT32 nlLen) 

| { 

: return memcmp((void *) pCmp1, (void *) pCmp2, nLen) ; 


ANSI functions are implemented to map one-to-one with the standard ANSI function. Each 
six functions execute the general memory operation: memory allocation, memory release, 


memory copy, memory set, and memory comparison. You must implement these 
mandatory functions. 


Add the following code in bold to implement Message print function. 


| VOID 

| OAM_Debug(VOID *pFmt, ...) 
4 

i static char aStr[4096]; 
va_list ap; 


va_start (ap, pFmt); 
vsprintf(aStr, (char *) pFmt, ap); 
printf (aStr) ; 


va_end (ap) ; 


Message print function prints messages on XSR. If you want to see an error or debug 
message of XSR, you should implement this function. 


Do not modify the semaphore functions because you use a single process, not a 
multi-process. The current template always returns TRUE32 . 


| BOOL32 
| OAM_CreateSM(SM32 *pHandle) 
if 


*pHandle = 1; 
return TRUE32; 


| BOOL32 
| OAM_DestroySM(SM32 nHandle) 
if 


return TRUE32; 
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| BOOL32 

| OAM_AcquireSM(SM32 nHandle) 
i{ 
/ return TRUE32; 
|} 


| BOOL32 

| OAM_ReleaseSM(SM32 nHandle) 
| 4 

i return TRUE32; 

[} 


For detailed information about the semaphore functions, refer to Chapter 4.2. OAM APIs. 
For detailed information about the semaphore functionality, refer to Chapter 7.1. 
Semaphore. 


7) Do not modify the interrupt functions because you do not use real NAND flash memory. 


| VOID 

| OAM_InitInt (UINT32 nLogIntId) 
iz 

i} 


| VOID 

| OAM_BindInt (UINT32 nLogIntId, UINT32 nPhyIntId) 
i{ 

i. 


| VOID 

| OAM_EnableInt (UINT32 nLogIntId, UINT32 nPhyIntId) 
i 

i} 


| VOID 

| OAM_DisableInt (UINT32 nLogIintId, UINT32 nPhyIntId) 
i 

(3 


| VOID 
| OAM_ClearInt (UINT32 nLogIntId, UINT32 nPhyIntId) 


1) 


For detailed information about the interrupt functions, refer to Chapter 4.2. OAM APIs. 


8) Do not modify timer functions because you do not real NAND flash memory. 
| VOID 
| OAM_Reset Timer (VOID) 


| UINT32 
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| OAM_Get Time (VOID) 
i 
return 0; 


| VOID 

I OAM_WaitNMSec(UINT32 nNMSec) 
{ 

|} 


For detailed information about timer functions, refer to Chapter 4.2. OAM APIs. For 
detailed information about timer functionality, refer to Chapter 7.2.5 Timer and 7.3 
Power-Off Recovery. 


The function OAM_Pa2Va is used for the address translation: from Physical address to 
Virtual address. Do not modify this function, because you do not use real NAND flash 
memory. 


| UINT32 

| OAM_Pa2Va(UINT32 nPAddr) 
| { 

| return nPAddr; 


E 


If it is needed to the address translation for accessing to hardware, you should implement 
this function. 


The function OAM_Id1e is called when XSR is at idle time. For example, if XSR is polling 
on the device status, this function is called. Do not modify this function for now. 


VOID 

| OAM_Idle (VOID) 
i 

LA 


At idle, other operations can be done by implementing this function. 


The function OAM_GetROLockF 1agq is called when XSR determines whether certain 
block is in Read-Only partition or not. If XSR finds it is in range of RO partition, this 
function is called. If it is necessary to regard blocks in RO partition as RW under certain 
condition, implement this function. Do not modify this function unless you deeply 
understand internal implementation of XSR. Default implementation of this function just 
returns TRUE. 


| BOOL32 

| OAM_Get ROLockF lag (VOID) 
| { 

| return TRUE32; 
i} 


After editing MyOAM.cpp, save the file and close it. 
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3.2.3. 


By far, you implement an OAM file, MyOAM.cpp, operating on Win32. Next, you 
implement LLD files. 


LLD Porting 


XSR sends a request to a device driver LLD, and then LLD accesses to the real device. This 
porting example shows you the process to make a simple NAND emulator as RAM, 
because you do not use real NAND flash memory. 


Suppose that the simple NAND emulator is as follows; 


O) pNANDArray, a general pointer variable, points to the start address of the simple 
NAND emulator. 


O Supposing that using large block, so 1 page = 4 sector. 

O11 page = (512 * 4) bytes main array + (16 * 4) bytes spare array . 
0 1 block = 64 pages. 

0) The total number of blocks = 1024. 

0 The total memory of the simple NAND emulator 


= the number of total blocks * (the number of pages in a block * the size of a page) 
= 1024 * (64 * (512 * 4+ 16 * 4)) bytes. 


| Block 


Pages in a Block 
: G4 


Total Blocks 
7124 


Figure 3-5. Simple NAND Emulator Design 


In \XSR\LLD folder, there are two template files in Template folder: MyLLD.h and 
MyLLD.cpp. A template file MyLLD.cpp contains 17 functions that are classified into 6 
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1) 


2) 


categories. 
Inilializalion functions : MyLLD_ init, MyLLD_Open, 
MWyLLO Close 
| Device Information Query functhon : MyLLD_ GeDevinfa | 


MyLLO Erase, MyLLO_MPRread, MyLLO_Mvrite, 


LLO Flash Operation functions © MyLLD Read. MyLLD_ Write, 
MyLLD_MErase, MyLLD EraseVerity 


Other functions : MyLLO_ChkiniiBadBik, MyLLD_SetRWaArea, 


| Copyback function : MyLLD_Copyback | 
MyLLD_IOcti | 


Deferred Check Operation functions : MyLLD_GetPrevOpData, 
NyLLD_FlushOp 


Figure 3-6. LLD Function Classification 


Now, make a simple NAND emulator and port LLD to that simple NAND emulator. 


Make a duplicate of the existing Template folder in \XSR\LLD, and name the new folder 
as MyLLD. 


Check there are two files MyLLD.cpp and MyLLD.h in the newly named folder MyLLD. 


Open the existing file MyLLD.h in an editor and check it. 
Do not modify MyLLD.h and use it as it is. 


|#ifndef __MY LLD_H 
| #define __MY_LLD_H 


| #ifdet cplusplus 
extern "C" { 
i#endif /* __cplusplus */ 


i INT32 MyLLD_Init (VOID *pParm); 

INT32 MyLLD_Open (UINT32 nDev); 

| INT32 MyLLD_Close (UINT32 nDev); 

| INT32 MyLLD_ChkInitBadBlk (UINT32 nDev, UINT32 nPbn); | 
| INT32 MyLLD_Read (UINT32 nDev, UINT32nPsn, UINT32 nNumOfScts, | 


UINTS8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag); 


INT32 MyLLD_Write (UINT32nDev, UINT32nPsn, UINT32nNumOfScts, 


UINT8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag); 


_INT32 MyLLD_Erase (UINT32 nDev, UINT32 nPbn, UINT32 nFlag); 
| INT32 MyLLD_CopyBack (UINT32 nDev, CpBkArg *pstCpArg, 


UINT32 nFlag); 


_ INT32 MyLLD_GetDeviInfo (UINT32 nDev, LLDSpec* pstLLDDev) ; 
i INT32 MyLLD_GetPrevOpData (UINT32 nDev, UINT8 *pMBuf, 
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UINT8 *pSBuf) ; 
/ INT32 MyLLD_FlushOp (UINT32 nDev); 

_ INT32 MyLLD_SetRWArea (UINT32 nDev, UINT32 n1stUB, 

i UINT32 nNumOfUBs) ; 

| INT32 MyLLD_IOCtl (UINT32 nDev, UINT32 nCode, UINT8 *pBufI, 

i UINT32 nLenI, UINT8 *pBufO, UINT32 nlLeno, 

i UINT32 *pByteRet) ; 

_ INT32 MyLLD_MRead (UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, 

i SGL *pstSGL, UINT8 *pSBuf,UINT32 nFlag) ; H 
| INT32 MyLLD_MWrite (UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, | 
i SGL *pstSGL, UINT8 *pSBuf, UINT32 nFlag, 

i UINT32 *pErrPsn) ; 

_ INT32 MyLLD_MErase (UINT32 nDev, LLDMEArg *pstMEArg, 

i UINT32 nFlag); 

| INT32 MyLLD_EraseVerify (UINT32 nDev, LLDMEArg *pstMEArg, 

i UINT32 nFlag); 


#ifdef __ cplusplus 
i 
| #endif /* __cplusplus */ 


| #endif /* MY_LLD_H * / 
If necessary, you can rename the prefix (MyLLD_) of LLD function suitable for the device. 
If you change the function name, save the file MyLLD.h and close it. 


3) Open the existing file MyLLD.cpp in an editor. 


4) Add the following code to make a simple NAND emulator. 
First, define the number of blocks and the size of total blocks to use. Then, define a general 
pointer variable pointing to the start address of the buffer for the simple NAND emulator. 


_#define NUM_BLK 1024 

i #define PGS_PER_BLK 64 

_#define SCTS_PER_PG 4 

| #define SCTS_PER_BLK (64 * 4) 

| #define PG_SIZE (512, * 2 + 16% A) 
(64 * PG_SIZE) 


| #define BLK_SIZE 
|UINT8 *pNANDArray; 
NUM_BLK is the number of the total blocks. It is defined as 1024. 


BLK_SIZE is the size of a block. The formula to decide the size of a block is the number of 
pages in a block * the size of a page = 64 * (512 *4 + 16 * 4). 


pNANDArray is a general pointer variable pointing to the start address of the simple 
NAND emulator. 


5) Add the following code in bold to implement Device initialization related functions: Init, 
Open and Close. 
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_ INT32 
| MyLLD_Init (VOID *pParm) 
if 


XsrvolParm *pstParm = (XsrVolParm*) pParm; 


pNANDArray = (UINT8 *)OAM_Malloc(NUM_BLK * BLK_SIZE) ; 

if (pNANDArray == NULL) 

{ 
LLD_RTL_PRINT ( (TEXT ("Memory Allocation Error!!\n"))); 
return LLD_INIT_FATILURE; 


} 
OAM_Memset (pNANDArray, Oxff, NUM_BLK * BLK_SIZE) ; 


return LLD SUCCESS; 


_ INT32 

| MyLLD_Open (UINT32 nDev) 
4 

; return LLD_SUCCESS; 


_ INT32 

| MyLLD_Close (UINT32 nDev) 
| { 

; return LLD_SUCCESS; 


Init initializes data structure required to the device operating. Init called first and once 
when the driver is loaded. 

This example allocates a buffer for the simple NAND emulator calling a function 
OAM _Malloc, and initializes the buffer as Oxff. In general, you can implement this 
function suitable for real NAND device. 


Open initializes the device to be used. 
Do not modify the template. In general, you can implement this function that makes the real 
device be ready to use. 


Close , in opposite to Open, unlinks XSR and the device. 
Do not modify the template. In general, you can implement this function that makes the real 
device be released. 


6) Add the following code in bold to implement Device information query function 
GetDevinfo. 


i INT32 
| MyLLD_GetDevInfo (UINT32 nDev, LLDSpec* pstDevinfo) 
| { 


pstDevInfo->nMCode = OxEC; 
pstDeviInfo-—>nDCode = 0x11; 
pstDeviInfo->nNumOfBlks = NUM_BLK; 
pstDevinfo->nPgsPerBlk = 64; 
pstDeviInfo->nSctsPerPg = 4; 
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pstDevInfo->nBlksInRsv = 20; 
pstDeviInfo->nNumOfPlane = 1; 


pstDevInfo->nBadPos = 0; 
pstDevInfo->nLsnPos = 2; 
pstDevInfo->nEccPos = 8; 
pstDeviInfo->nMEFlag = LLD_ME_NO; 
pstDeviInfo->nBWidth = 0; 


pstDeviInfo->aUID[ 0] = 
pstDeviInfo->aUID[ 1] = 
pstDeviInfo->aUID[ 2] = 
pstDeviInfo->aUID[ 3] = 
pstDeviInfo->aUID[ 4] = 
pstDevInfo->aUID[ 5] = 
pstDeviInfo->aUID[ 6] = 
pstDeviInfo->aUID[ 7] = 
pstDeviInfo->aUID[ 8] = 
pstDeviInfo->aUID[ 9] = 
pstDevInfo->aUID [10] = 
pstDevInfo->aUID[11] = 
pstDevInfo->aUID [12] = 
pstDevInfo->aUID [13] = 
pstDevInfo->aUID [14] = 
pstDeviInfo->aUID[15] = 


Ne Ne Ne Ne Ne Ne 


oN 


Ne Ne Ne Ne Ne Ne Ne 


oooooooo0oo0o0o0oo0o0°oCc°o 


~e 


pstDeviInfo->nTrTime = 500000; 
pstDeviInfo->nTwTime 3500000; 
pstDeviInfo->nTeTime 20000000; 
pstDeviInfo->nTfTime = 50; 


return LLD_SUCCESS; 


GetDeviInfo returns the device information to BML. 


0 nMCode and nDCode are Device IDs. 
This example gives random code as OxEC and 0x11 because you do not use a real device. 


OC nNumOfBlks is the number of blocks, nPgsPerB1k is the number of pages in a block, 


0 nSctsPerPg is the number of sectors in a page, and nB1LksInRsv is the number of 
the reserved blocks. 


OO nMEF lag isa flag which indicates whether multi-block erase is supported or not. 


C1 aUID is Unique ID of a device. 
This example gives random code as 0 because you do not use a real device. 


Ol ntrtTime is the time for page reading, nTwTime is the time for page writing, nTeTime 
is the time for block erasing, nT£Time is the time for data transmitting (512 bytes). These 
values are referred as XSR mapping. 

These time values are the standard to calculate the performance cost for the internal 
algorithm. The time values should be suitable for the real operation time approximately, 
although it is not exactly same. The unit of the operation time is ns. 
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For more information about the device information to BML, refer to LLD API, 
XXX_GetDevinfo. 


Add the following code in bold to implement Flash operation functions: Read, Write, 
Erase, MRead, MWrite, MErase and EraseVerify. 


, INT32 

i MyLLD_| Read (UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, 
| UINT8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag) 

i 

i UINT32 nB1kOff; 

UINT32 nPgOff; 

UINT32 nSctOff; 

UINT32 nPos; 


nB1lkOff = nPsn / SCTS_PER_BLK; 

nPgOff = (nPsn — nB1kOff * SCTS_PER_BLK) / SCTS_PER_PG; 
nSctOff =nPsn- (nB1kOff * SCTS_PER_BLK+nPgOff * SCTS_PER_PG) ; 
nPos = nBlkOff * BLK_SIZE + nPgOff * PG_SIZE; 


if (pMBuf != NULL) 


{ 
PAM _Memcpy (pMBuf, pNANDArray + nPos + 512 * nSctOff, 
512 * nNumOfScts) ; 
} 
if (pSBuf != NULL) 
{ 
PAM _Memcpy (pSBuf, pNANDArray + nPos + 512 * 4+16*nSctOff, 
16 * nNumOfScts) ; 
} 


return LLD SUCCESS; 


Read is to read data as a unit of a sector from NAND flash memory. 

The parameters nPsn and nNumOfScts read data as a unit of a sector. The number of 
sectors does not exceed the sector-included page because you can read/write as a unit of a 
page. That is, this function reads data as a unit of a page; else the argument of the function 
is received as a unit of a sector. So, the number of sectors is limited by the number of a 
page. 

This example calculates the start address of memory using pNANDArray, and copies data 
to the using buffer. This function handles the main array and spare array separately when 
reading data of NAND flash memory page. 


_ INT32 

i MyLLD | Write (UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, 
UINT8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag) 
je 
! UINT32 nIdx; 
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UINT32 nSctIdx; 


UINT32 nB1kOff; 
UINT32 nPgOff; 
UINT32 nSctOff; 
UINT32 nPos; 


nB1lkOff = nPsn / SCTS_PER_BLK; 

nPgOff = (nPsn — nB1kOff * SCTS_PER_BLK) / SCTS_PER_PG; 
nSctOff =nPsn- (nB1kOff * SCTS_PER_BLK+nPgOff * SCTS_PER_PG) ; 
nPos = nBlkOff * BLK_SIZE + nPgOff * PG_SIZE; 


if (pMBuf != NULL) 


{ 
for (nSctIdx = 0; nSctIdx < nNumOfScts ; nSctIdx++) 
{ 
for (nIdx = 0; nIdx < 512; nIdx++) 
{ 
PNANDArray [nPos + 512 * (nSctOff + nSctIdx) + nIdx] 
&= pMBuf[512 * nSctIdx + nIdx]; 
} 
} 
} 
if (pSBuf != NULL) 
{ 
for (nSctIdx = 0; nSctIdx < nNumOfScts ; nSctIdx++) 
{ 
for (nIdx = 0; nIdx < 16; nIdx++) 
{ 
PNANDArray [nPos + 512 * 4+ 16 * (nSctOff + nSctIdx) | 
+ nIdx] &= pSBuf[16 * nSctIdx + nIdx]; | 
} i 
} 
} 


return LLD_SUCCESS; 


Write is to write data as a unit of a page or sector to NAND flash memory. 

The parameters nPsn and nNumOfScts read data as a unit of a sector. The number of 
sectors does not exceed the sector-included page because you can read/write as a unit of a 
page. That is, this function writes data as a unit of a page, else the argument of the function 
is received as a unit of a sector. So, the number of sectors is limited by the number of a 


page. 


This example calculates the start address of memory using pNANDArray, and writes data. 
This function always handles main array and spare array separately when it reads data of 
NAND flash memory page. You use an AND operator to emulate the real writing to NAND 
flash memory in this function. 


| INT32 
| MyLLD_Erase (UINT32 nDev, UINT32 nPbn, UINT32 nFlag) 


if 
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OAM_Memset (pNANDArray + nPbn * BLK_SIZE, Oxff, BLK_SIZE) ; 


return LLD_ SUCCESS; 


Erase is to erase a block of NAND flash memory. 

This example calculates the start address of memory using pNANDArray, and erases data. 
This example handles as a unit of a block. You fill memory buffer with Oxff. In general, 
you can implement this function that accesses to the real NAND device. 


INT32 
MyLLD_MRead(UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, 
SGL *pstSGL, UINT8 *pSBuf, UINT32 nFlag) 
{ 
UINT32 nB1kOff; 
UINT32 nPgOff; 
UINT32 nSctOff; 
UINT32 nPos; 
UINT32 nCnt; 
UINT32 nReadScts; 
UINT32 nSctIdx; 
UINT32 nCurPos; 


nB1lkOff = nPsn / SCTS_PER_BLK; 
nPgOff = (nPsn — nB1kOff * SCTS_PER_BLK) / SCTS_PER_PG; 
nSctOff =nPsn- (nB1kOff * SCTS_PER_BLK+nPgOff * SCTS_PER_PG) ; 


nPos = nBlkOff * BLK_SIZE + nPgOff * PG_SIZE; 
nCurPos = nPos; 
nSctIdx = nSctOff; 


if (pstSGL != NULL) 
{ 
for (nCnt = 0;nCnt < pstSGL->nElements; nCnt++) 
{ 
nReadScts = 0; 
while (nReadScts < pstSGL->stSGLEntry [nCnt] .nSectors) 
{ 
PAM_Memcpy ( 
pstSGL->stSGLEntry [nCnt] .pBuf + 512*nReadScts, 
PNANDArray + nCurPos + 512 * nSctIdx, 512); 


nReadScts++; 
nSctIdx++; 
if (nSctIdx == 4) 
{ 
nCurPos += PG_SIZE; 
nSctIdx = 0; 


if (pSBuf != NULL) 
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PAM _Memcpy (pSBuf, pNANDArray + nPos + 512 * 4+16* nSctOff, 
16 * nNumOfScts) ; 


return LLD_SUCCESS; 


MRead reads pages and sectors within a block boundary, while Read reads data within a 
page. This function can be optimized by not reading sectors one by one. But, for simplicity, 
the above scheme shows how to handle SGL argument. 


i INT32 

| MyLLD_MWrite (UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, 
; SGL *pstSGL, UINT8 *pSBuf, UINT32 nFlag, 
UINT32 *pErrPsn) 


UINT32 nIdx; 
UINT32 nB1kOff; 
UINT32 nPgOff; 
UINT32 nSctOff; 
UINT32 nPos; 
UINT32 nCnt; 
UINT32 nWriteScts; 


UINT32 nSctIdx; 
UINT32 nCurPos; 
UINT8 *pSrcBuf; 


nB1lkOff£ = nPsn / SCTS_PER_BLK; 
nPgOff = (nPsn — nB1kOff * SCTS_PER_BLK) / SCTS_PER_PG; 
nSctOff =nPsn- (nB1kOff * SCTS_PER_BLK+nPgOff * SCTS_PER_PG) ; 


nPos = nBlkOff * BLK_SIZE + nPgOff * PG_SIZE; 


nCurPos = nPos; 
nSctIdx = nSctOff; 
if (pstSGL != NULL) 


{ 
for (nCnt = 0;nCnt < pstSGL->nElements;nCnt++) 
{ 
nWriteScts = 0; 
pSrcBuf = pstSGL->stSGLEntry [nCnt] .pBuf; 
while (nWriteScts<pstSGL->stSGLEntry [nCnt] .nSectors) 
{ 
for (nIdx = 0; nIdx < 512; nIdx++) 
{ 
PNANDArray[nCurPos + 512*nSctIdx + nIdx] 
&= pSrcBuf[512*nWriteScts + nIdx]; 
} 


nWriteScts+t; 


nSctIdx++; 
if (nSctIdx == 4) 
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return LLD_ SUCCESS; 


| { 

| nCurPos += PG_SIZE; 

| nSctIdx = 0; 

I } 

i } 

| } 

| } 

if (pSBuf != NULL) 

{ 

| for (nSctIdx = 0; nSctIdx < nNumOfScts ; nSctIdx++) 
{ 

| for (nIdx = 0; nIdx < 16; nIdx++) 

{ 

i PNANDArray [nPost+512*4+16* (nSctOff+nSctIdx) +nIdx] 
| &= pSBuf[16 * nSctIdx + nIdx]; 

| } 

| } 

I } 

i} 


MWrite writes pages and sectors within a block boundary, while Write writes data within 
a page. This function can be optimized by not writing sectors one by one. But, for 
simplicity, the above scheme shows how to handle SGL argument. 


i INT32 

| MyLLD_MErase (UINT32 nDev, LLDMEArg *pstMEArg, UINT32 nFlag) 
i 

i return LLD_SUCCESS; 


MErase erases multiple blocks of NAND flash memory simultaneously, while Erase 
erases only one block of NAND flash memory. In this example, we assume that NAND 
emulator does not support an erase operation for multiple blocks, thus MErase is not 
provided. 


| INT32 

/ MyLLD_EraseVerify (UINT32 nDev, LLDMEArg *pstMEArg, UINT32 nFlag) 
Ia 

i return LLD_SUCCESS; 


EraseVerify verifies an erase operation whether it checks blocks are properly erased. 
Do not modify the template. In this example, we assume that NAND emulator does not 
support an erase operation for multiple blocks, thus EraseVeri fy is not provided. 


8) Add the following code in bold to implement CopyBack function. CopyBack function 
supports a page copy functionality using the internal buffer in a NAND device. 
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i: INT32 
| MyLLD_CopyBack (UINT32 nDev, CpBkArg *pstCpArg, UINT32 nFlag) 


i 


UINT8 aBuf[2112]; 
UINT32 nIdx; 
UINT32 nB1kOff; 
UINT32 nPgOff; 
UINT32 nSctNum; 
UINT32 nOffset; 
UINT32 nPos; 


nB1kOff = pstCpArg->nSrcSn / SCTS_PER_BLK; 

nPgOff = (pstCpArg->nSrcSn —- nBlkOff * SCTS_PER_BLK) 
/ SCTS_PER_PG; 

nPos = nBlkOff * BLK_SIZE + nPgOff * PG_SIZE; 


PAM Memcpy (aBuf, pNANDArray + nPos, 2112); 


for (nIdx = 0; nIdx < pstCpArg->nRndInCnt; nIdx++) 
{ 


nSctNum pstCpArg->pstRndInArg[nIdx] .nOffset / 1024; 
nOffset = pstCpArg->pstRndInArg[nIdx] .nOffset % 1024; 


if (nOffset < 512) 


{ 

PAM _Memcpy (aBuf + 512 * nSctNum + nOffset, 
pstCpArg->pstRndInArg [nIdx] .pBuf, 
pstCpArg->pstRndInArg [nIdx] .nNumOfBytes) ; 

} 
else 
{ 

PAM_Memcpy (aBuf + 512 * 4 + 16 * nSctNum + nOffset, 
pstCpArg->pstRndInArg [nIdx] .pBuf, 
pstCpArg->pstRndInArg [nIdx] .nNumOfBytes) ; 

} 


} 


nB1lkOff = pstCpArg->nDstSn / SCTS_PER_BLK; 
nPgOff = (pstCpArg->nDstSn —- nBlkOff * SCTS_PER_BLK) 
/ SCTS_PER_PG; 


nPos = nBlkOff * BLK_SIZE + nPgOff * PG_SIZE; 
for (nIdx = 0; nIdx < 2112; nIdx++) 
{ 
PNANDArray[nPos + nIdx] &= aBuf[nIdx]; 
} 


return LLD_SUCCESS; 


@ Reference 


CopyBack means the operation method to copy pages using the internal buffer in a 
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NAND device. 

This copyback method improves the performance by cutting the transfer time and 
operation procedure, because this method does not use the external memory. When 
copying a page using the copyback method, a part of data can be brought the outside 
device; this is called Random-in. 

To implement CopyBack function, you must understand a CpBkArg structure. For more 
information about CpBkArg, refer to LLD function XXX_CopyBack. 


Do not modify Chk InitBadBlk, SetRWArea, and IOCt1 functions, because you use 
the simple NAND emulator. 


i INT32 
| MyLLD_ChkInitBadB1k (UINT32 nDev, UINT32 nPbn) 
1 { 


return LLD_INIT_GOODBLOCK; 


| INT32 
| MyLLD_SetRWArea (UINT32 nDev, UINT32 nlstUB, UINT32 nNumOfUBs) 
4 


return LLD_SUCCESS; 


| INT32 
| MyLLD_IOCt1(UINT32 nDev, UINT32 nCode, UINT8 *pBufl, 


UINT32 nLenI, UINT8 *pBufO, UINT32 nLeno, 
UINT32 *pByteRet) 


return LLD SUCCESS; 


ChkInitBadBLk is to check whether a block is an initial bad block or not. 

If the value of the bad mark position in the first or second page of a block is not Oxff(a 
normal statement), the block is the initial bad block. 

This function is implemented to read the first or second page of a block and check it bad or 
not. In general, you implement this function using Read function in real NAND device. 


SetRWArea is used when NAND device supports the hardware write protection. 


Do not modify Deferred Check Operation functions. The current template always returns 
LLD_SUCCESS. 


: INT32 
| MyLLD_GetPrevOpData (UINT32 nDev, UINT8 *pMBuf, UINT8 *pSBuf) 
| { 


return LLD_SUCCESS; 


| INT32 
| MyLLD_FlushOp (UINT32 nDev) 
if 


return LLD SUCCESS; 
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3.2.4. 


E 


For detailed information about the function related to Deferred Check Operation, refer to 
Chapter 5.2. LLD APIs. For detailed information about the functionality of Deferred Check 
Operation, refer to Chapter 7.4. Deferred Check Operation. 


After editing MyLLD.cpp, save the file and close it. 


By far, you make a simple NAND emulator and port the device driver file MyLLD.cpp 
operating to the simple NAND emulator. Next, you implement a PAM file. 


PAM Porting 


PAM, a platform-dependent module, links XSR to the platform. This document shows you 
the process to port OAM to Win32 and port LLD by making a simple NAND emulator. 
You implement PAM based on that porting environment. 


In \Platform\PAM directory, there is a template file MyPAM.cpp in Template folder. 
This template file contains 9 functions as follows. 


Device Configuration functions : PAM_RegLFT, PAM _PAParm 


Interrupt functions : PAM_InitInt, PAM_BindInt, PAM_Enablelnt 
PAM_Dlsablelnt, PAM_Clearint 


Figure 3-7. PAM Function Classification 


Now, port PAM to the simple NAND emulator made by LLD. 


Make a duplicate of the existing Template folder in \Plat form\PAM, and name the new 
folder as MyPAM. 


Check that there is a file MyPAM.cpp in the newly named folder MyPAM. 
Open the existing file MyPAM.cpp in an editor. 
Update the path of a LLD header file as follows. 


oO Before Modification 
i#include "../../../XSR/LLD/Template/MyLLD.h" 
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OO After Modification 


i #include ". 


-/../../XSR/LLD/MyLLD/MyLLD.h" 


Depending on the type of the released package, the proper path of LLD header files can be 
different from above. 


Do not modify initialization functions because you do not real NAND flash memory. 


| VOID 


| PAM_Init (VOID) 


| 4 
[3 


Add the following code in bold to implement a function RegLFT, which registers LLD to 


XSR. 


_ VOID 


if 


pstLFT 

pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
pstLFT [0] 
PsStLFT [0] 
pstLFT [0] 


PAM RegLFT (VOID *pstFunc) 


LowFuncTbl *pstLFT; 


.Init 

.Open 

.Close 

.Read 

.Write 

. CopyBack 

. Erase 
.GetDevinfo 
.ChkInitBadB1lk 
.FlushOp 

. SetRWArea 
.GetPrevOpData 
.Toctl1 

.MRead 

.MWrite 
.MErase 
.EraseVerify 


RegLFT registers LLD to BML. 
If you change LLD function name in MyLLD.cpp and MyLLD h, you must rename LLD 
function name in this function. 


Add the following code in bold to implement a function Get PAParm, which configures 


the platform and device. 


_#define vo 
i #define 


LO 0 


VoL. 1 


(LowFuncTb1*) pstFunc; 


MyLLD_Init; 
MyLLD_Open; 
MyLLD_Close; 
MyLLD_Read,; 
MyLLD_Write; 


MyLLD_CopyBack; 


MyLLD_Erase; 


MyLLD_GetDevinfo; 
MyLLD_ChkInitBadBlk; 


MyLLD_FlushoOp; 


MyLLD_SetRWArea; 
MyLLD_GetPrevOpData; 


MyLLD_tIoctl1; 
MyLLD_MRead,; 
MyLLD_MWrite; 
MyLLD_MErase; 


MyLLD_EraseVerify; 
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(define DEVO 


ft) 
(#define DEVI 1 
/#define DEV2 2 
_#define DEV3 3 
| VoID* 
| PAM_Get PAParm (VOID) 


gstParm[VOLO] .nBaseAddr [DEVO] = 0x20000000; 
gstParm[VOLO] .nBaseAddr[DEV1] = NOT_MAPPED; 
gstParm[VOLO] .nBaseAddr [DEV2] = NOT_MAPPED; 
gstParm[VOLO] .nBaseAddr [DEV3] = NOT_MAPPED; 


gstParm[VOLO] .nEccPol = SW_ECC; 
gstParm[VOLO] .nLSchemePol = SW_LOCK_SCHEME; 
gstParm[VOLO] .bByteAlign = FALSE32; 
gstParm[VOLO] .nDevsInVol = 1; 
gstParm[VOLO] .pExInfo = NULL; 


return (VOID *) gstParm; 


GetPAParm returns the information to XSR and LLD. 

This example only implements [VOLO] and [DEVO] because this example uses | device. 
[VOLO] has the following functionalities: it uses software ECC, it uses the software lock 
scheme, and it does not use byte aligning. In general, you must implement the total setting 
about nBaseAddr[ ]as many as the device number per a volume. 


7) Do not modify the interrupt functions because you do not use real NAND flash memory. 


| VOID 

| PAM_InitInt (UINT32 nLogIntId) 
i 

i} 


/ VOID 

| PAM_BindInt (UINT32 nLogIntId) 
| { 

e 


| VOID 

| PAM_EnableInt (UINT32 nLogIntId) 
| { 

i} 


} VOID 

| PAM_DisableInt (UINT32 nLogIntId) 
| { 

i} 


| VOID 
| PAM_ClearInt (UINT32 nLogIntId) 
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3.2.5. 


For detailed information about the interrupt functionality, refer to Chapter 7.2. Interrupt. 


Do not modify the memory copy function because you do not use real NAND flash 
memory. 


| VOID 
| PAM_Memcpy (VOID *pDst, VOID *pSrc, UINT32 nLen) 
if 


OAM Memcpy(pDst, pSrc, nlLen); 


PAM Memcpy copies data from source to destination using system supported function. In 
this porting example, PAM_Memcpy just calls OAM_Memcpy because you do not use real 
platform. 


After editing MyPAM.cpp, save the file and close it. 


By far, you implement MyPAM.cpp. You implement all required porting files, so create the 
application to execute XSR. 


Application Creating 
Now, create the application using the implemented files and test that XSR operates well. 


To make a main file of the project, add the following code in an editor and name it as 
XSRHello.cpp in XSR folder. 


| #include <XSR.h> 
| #include <stdio.h> 


| #define NUM_OF_VOLS 2 
#define VOLO 0 
| #define VOL1 i 
|UINTS aRWBuf [512]; 
_INT32 


| SeqWrite (UINT32 nTotalLogScts) 
if 


UINT32 nidx; 
UINT32 nIdx2; 
INT32 nErr; 
printf (" ") 3 


for (nIdx = 0; nIdx < nTotalLogScts; nIdx+t+) 

{ 
printf ("\b\b\b\b\b\b\b\b%-8d", nTotalLogScts - nIdx); 
for (nIdx2 = 0; nIdx2 < 512; nIdx2++) 
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{ 
aRWBuf [nIdx2] = (UINT8) (nIdx + 


} 


nIdx2); 


nErr = STL_Write(VOLO , PARTITION_ID_FILESYSTEM, 


nidx, 1, aRWBuf); 
if (nErr != STL_SUCCESS) break; 


} 
printf ("\b\b\b\b\b\b\b\b") ; 


return nErr; 


| INT32 
| SeqVerify (UINT32 nTotalLogScts) 
| 


UINT32 nidx; 
UINT32 nIldx2; 
INT32 nErr; 


for (nIdx = 0; nIdx < nTotalLogScts; 
{ 


nidx+t+) 


nErr = STL_Read(VOLO , PARTITION_ID_FILESYSTEM, 


nidx, 1, aRWBuf); 
if (nErr != STL_SUCCESS) break; 


for (nIdx2 = 0; nIdx2 < 512; nIdx2++) 


if (aRWBuf[nIdx2] != (UINTS8) (nIdx + nIdx2) ) 


if (nIdx2 < 512) 


nErr = 1; 
break; 


return nErr; 


| VOID 

| main (VOID) 
i{ 
; STLInfo stSTLinfo; 


STLConfig stSTLconfig; 
XSRPartI stPart [NUM_OF_VOLS]; 
INT32 nErr; 

UINT32 nTotalLogScts; 
UINT32 nidx; 


printf ("### Hello XSR ###\r\n"); 


do 


{ 
STL_Init (); 


OAM Memcpy (&stPart [VOLO].aSig, "XSRPARTI", 
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| 
d 


BML_MAX PART_SIG) ; 


stPart [VOLO] .nVer 
stPart [VOLO] .nNumOfPartEntry 


0x00010000; 
1; 


stPart [VOLO].stPEntry[0].nID = 
PARTITION_ID_FILESYSTEM; 


stPart [VOLO].stPEntry[0].nAttr = BML PI_ATTR_RW; 
stPart [VOLO].stPEntry[0].nlstVbn = 0; 
stPart [VOLO].stPEntry[0].nNumOfBlks = 100; 
nErr = BML Format (VOLO, é&stPart [VOLO], 
BML_INIT_FORMAT) ; 
if (nErr != BML SUCCESS) 
{ 
printf ("({:ERR] BML_Format() returns ERROR : %x\r\n", 
nErr); 
break; 
} 
stSTLconfig.nFillFactor = 100; 
stSTLconfig.nNumOfRsvUnits = 2; 
stSTLconfig.nBlksPerUnit = 1; 
stSTLconfig.nSnapshots = 4; 


nErr = STL_Format (VOLO, PARTITION_ID_FILESYSTEM, 
&stSTLconfig , 0); 


if (nErr != STL_SUCCESS) 
{ 
printf("({:ERR] STL_Format() returns ERROR : %x\r\n", 
nErr); 
break; 
} 
stSTLinfo.nSamBufFactor = 100; 


ll 


stSTLinfo.bASyncMode FALSE32; 


nErr = STL_Open(VOLO, PARTITION_ID_FILESYSTEM, 


&stSTLinfo); 
if (nErr != STL_SUCCESS) 
{ 
printf("[:ERR] STL_Open() returns ERROR : %x\r\n", 


nErr); 
break; 


nTotalLogScts = stSTLinfo.nTotalLogScts; 


printf("* Simple Test()\r\n"); 
for (nIdx = 0; nIdx < 10; nIdx+t+) 
{ 
printf("\t(%2d) Write : ", nIdx + 1); 
if (SeqWrite(nTotalLogScts) == STL_SUCCESS) 
{ 
printf ("OK\r\n"); 
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2) 


} 
} while (0); 


STL_Close(VOLO, PARTITION_ID_FILESYSTEM) ; 


printf ("### Bye XSR ###\r\n"); 


else 

| 

| printf ("ERROR\r\n") ; 

break; 

i printf ("\t Verify : ", nIdx + 1); 
| if (SeqVerify(nTotalLogScts) == STL_SUCCESS) 
i { 

printf ("OK\r\n"); 

| 

i else 

| 

i printf ("BRROR\r\n"); 

break; 

| 

3 


Execute Visual Studio, and create a new Win32 Console project. 
This is an example to name the new project as XSRHello. 


Include the following files in the new project XSRHello. 
Then, you can see the project structure as the following figure. 


OO XSR\XSRHello.cpp 

XO XSR\OAM\MyOAM\MyO~AM. cpp 

O XsR\LLD\MyLLD\MyLLD . cpp 

MyLLD.h 

O XSR\Inc\BML. 
LLD. 
OAM . 
PAM. 
STL. 
XSR. 
XsrTypes.h 

O XSR\lib\Generic\VS60\Retail\XSREmul .1ib 

O Platform\PAM\MyPAM\MyPAM. cpp 


pores op 
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i) Workspace 'XSRHello': 1 project(s) 
-| 2] XSRHello files 
- 
[¥] MyLLD.cpp 
[=] MyOAM.cpp 
|=] MyPAM.cpp 
[#] XSRHello.cpp 
= <q Header Files 
[2] BML.h 
[=] LLD.h 
(3 MyLLD.h 
[2] OAM.h 
{=) PAM.h 
[2] STL.h 
[2] XSR.h 
[2] XsrTypes.h 
(-) Resource Files 
[2] XsrEmul.lib 


™"ClassView 2] FileView 


Figure 3-8. XSRHello Project Structure 


4) On Project menu, click Setting, and then Project Setting pop-up window is opened. 


On Project Setting pop-up window, set as follows. 


O On C/C++ tap, click General in Category list. 


Add “, OAM_RTLMSG_ENABLE” in Preprocessor definitions text box. 


@ Reference 


If you declare OAM_RTLMSG_ENABLE, XSR_RTL_PRINT () 


OAM_Debug () function. 


If you declare OAM_DBGMSG_ENABLE, XSR_DBG_PRINT() 


OAM_Debug () function. 


function is linked to 


function is linked to 


O On C/C++ tap, click Preprocessor in Category list. 


Add “../../inc” in Additional include directories text box. 


Now, all preparation for executing XSRHello project is done. 


5) Click Execute XSRHello.cpp on Build menu, or press Ctrl + F5 key, or click : button 


on menu toolbar. Then, the project is executed. 


The project is compiled and built if there is no error, and the project is performed. 
The command window is opened, so you can XSRHello project is working. 
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_### Hello XSR ### 
'* Simple Test () 
(1) Write : OK 
Verify : OK 
( 2) Write : OK 
Verify : OK 
( 3) Write : OK 
Verify : OK 
( 4) Write : OK 
Verify : OK 
( 5) Write : OK 
Verify : OK 
( 6) Write : OK 
Verify : OK 
( 7) Write : OK 
Verify : OK 
( 8) Write : OK 
Verify : OK 
( 9) Write : OK 
Verify : OK 
(10) Write : OK 
i Verify : OK 
_### Bye XSR ### 
i Press any key to continue 


Figure 3-9. XSRHello Project Working Screen 


XSRHello project working process is as follows; 


1. First, call STL_Init, 

2. Format BML 

3. Format STL 

4. Open STL, 

5. Then, repeat Sequential Write and Sequential Verify 10 times. 


@ Remark 


The preceding API calling sequence is for the NAND device that is called for the first 
time. BML_Format () should be called just one time to initialize NAND device. And 
STL_Format() should be called for each RW partitions. If BML_Format () and 
STL_Format() are called for the NAND device before, STL_Init() and 
STL_Open () are enough to next opening the NAND device. 


@ Reference 


Sequential Write means writing data from the sector 0 to the last as many as defined 
sequentially. 

Sequential Verify means verifying the written data from the sector 0 to the last as many as 
defined sequentially. 


Once all working is finished, it shows “### Bye XSR ###”. Press any key to close 
XSRHello command window. 
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You follow XSR porting example and execute it. Now, you can port XSR in various 
environments by implementing OAM, LLD and PAM. 
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4. OAM (OS Adaptation Module) 


This chapter describes the definition, system architecture, features, and APIs of OAM. 


4.1. Description & Architecture 


OAM is an abbreviation of OS Adaptation Module. OAM is to receive the services that OS 
provides. OAM is responsible for OS-dependent part of XSR layers (STL and BML). If OS 
is changed, a user only changes OAM. 


For example, a layer of XSR wants to write memory. The memory request service is 
dependent on OS. Each layer calls an adaptation module OAM to use OS functionalities. 
Therefore a user must implement OAM suitable for the OS when a user ports XSR. 


Figure 4-1 shows OAM in XSR system architecture. 


POeeeee eee e eter t errr terete teeter creer ererierretererrriritricitrtrtrrrriertrirrrerrititririertertrrrrerrrtrrrrrrrerrrrrrrrenrnds * 


File System 
| 


Block Device Interface 


Logical Flash Address 


XSR Core 


Sector Translation Layer 


| Virtual Flash Address 


Block Management Layer 


Platform Adaptation 
Module 


Physical Flash Address 


Low Level Device Driver 


NAND Flash Memory 


Figure 4-1. OAM in XSR System Architecture 


OAM has 21 functions that are classified into 6 categories as follows. 


O ANSI functions : memory allocation, memory free, memory copy, memory setting, and 
memory comparison 
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Oo Message print function : message print 


O Semaphore functions: semaphore creation, semaphore destroy, semaphore acquire, and 
semaphore release 


O Interrupt functions: interrupt initialization, interrupt bind, interrupt enable, interrupt 
disable, and interrupt clear 


QO Timer functions : timer setting, timer return, and time waiting 


O Other functions : address translation, idle operation, RO partition check 


In the next chapter, OAM APIs are covered in detail. 
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4.2. API 


This chapter describes OAM APIs. . 


@ Reference 


All the OAM function has a prefix “OAM_” on each function name. 


Table 4-1 shows the lists of OAM APIs. 

The right row in table shows that the function is Mandatory or Optional or Recommended. 
Optional functions should be existed, but contents of the functions does not need to be 
implemented. 


Table 4-1. OAM API 


Function Description 

OAM_Malloc This function allocates memory for XSR. M 

OAM_Free This function frees memory that XSR allocates. M 

OAM _Memcpy This function copies from the source data to the M 
destination data. 

OAM_Memset This function sets data of a specific buffer. M 

OAM_Memcmp This function compares data of two buffers. M 

OAM_Debug This function is called when XSR prints message. R 

OAM_CreateSM This function creates the semaphore. O 

OAM_DestroySM This function destroys the semaphore. O 

OAM_AcquireSM This function acquires the semaphore. O 

OAM_ReleaseSM This function releases the semaphore. O 

OAM _InitInt This function initializes the specified logical interrupt O 
for NAND device. 

OAM_BindInt This function binds the specified interrupt for NAND O 
device. 

OAM_EnableInt This function enables the specified interrupt for NAND | O 
device. 

OAM_DisableInt This function disables the specified interrupt for O 
NAND device. 

OAM_ClearInt This function clears the specified interrupt for NAND O 
device. 

OAM_ResetTimer This function resets timer. O 

OAM_Get Time This function returns the current time value. O 

OAM_WaitNMSec This function is called for delaying as a unit of R 
milliseconds. 

OAM_Pa2Va This function is called for the address translation to R 
access to the hardware from the system using virtual 
memory. 

OAM_Idle This function is called at idle time. O 

OAM_GetROLockFlag | This function is called when XSR determines whether O 
Partition is RO or not. 
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OAM_Malloc 


DESCRIPTION 
This function allocates memory for XSR. 
SYNTAX 


VOID * 
OAM _MallocC (UINT32 nSize) 


PARAMETERS 

Parameter Type In/Out Description 

nSize UINT32 In Size to be allocated 
RETURN VALUE 

Return Value Description 

VOID allocated memory buffer pointer 

If this function fails, the return value is NULL. 

REMARKS 


This function is a mandatory ANSI function. ANSI function is implemented to map 
one-to-one with the standard ANSI function. 


This function is called by the function that wants to use memory. 


EXAMPLE 


(1) Example to call the function ; 


| #include <OAM.h> 
| #include <XSRTypes.h> 


| VOID 
i Example (VOID) 
1 { 
UINT8 *MainBuf = (UINT8 *)OAM Malloc(512); 


j OAM _ Free (MainBuf) ; 
| } 


i void * 
| OAM_Malloc (UINT32 nSize) 
i{ 


(2) Example to implement the function in Symbian 


return Kern: :Alloc(nSize)j; 


SEE ALSO 
OAM_ Free 
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OAM _Free 


DESCRIPTION 
This function frees memory that XSR allocates. 
SYNTAX 


VOID 
OAM_Free(VOID *pMem) 


PARAMETERS 


Parameter Type In/Out Description 
pMem VOID * In Pointer to be free 


RETURN VALUE 
None 
REMARKS 


This function is a mandatory ANSI function. ANSI function is implemented to map 
one-to-one with the standard ANSI function. 


This function is called by the function that wants to free memory. 


EXAMPLE 


(1) Example to call the function ; 


| #include <OAM.h> 
| #include <XSRTypes.h> 


| VOID 
| Example (VOID) 
| { 
UINT8 *MainBuf = (UINT8 *)OAM Malloc(512); 


: OAM _ Free (MainBuf) ; 
i} 


(2) Example to implement the function in Symbian 
| VOID 
| OAM_Free (VOID *pMem) 
if 
/ Kern: :Free (pMem) ; 

return ; 


SEE ALSO 
OAM Malloc 
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OAM_Memcpy 


DESCRIPTION 
This function copies from the source data to the destination data. 
SYNTAX 


VOID 
OAM _Memcpy (VOID *pDst, VOID *pSrc, UINT32 nlLen) 


PARAMETERS 
Parameter Type In/Out Description 
pDst VOID * Out Array Pointer of destination data to be copied 
pSrce VOID * In Array Pointer of source data to be copied 
nLen UINT32 In Length to be copied 
RETURN VALUE 
None 
REMARKS 


This function is a mandatory ANSI function. ANSI function is implemented to map 
one-to-one with the standard ANSI function. 


This function is called by the function that wants to copy data in the source buffer to data in 
the destination buffer. 


EXAMPLE 


| #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


| VOID 

| Example (VOID) 

if 

/ UINT8 *SrcBuf = (UINT8 *)OAM Malloc(512) 
UINT8 *DstBuf = (UINT8 *)OAM Malloc(512) 


~NeoNe 


i OAM Memcpy (DstBuf, SrcBuf, (512)); 
i} 


(2) Example to implement the function in Symbian 
| VOID i 
| OAM_Memcpy (VOID *pDst, VOID *pSrc, UINT32 nLen) 
if 
| memcpy ((TAny*) (pDst), (const TAny*) (pSrc), 

(unsigned int)nLen); 
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SEE ALSO 
OAM _Memset, OAM _Memcmp 
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OAM_Memset 


DESCRIPTION 
This function sets data of a specific buffer. 
SYNTAX 


VOID 
OAM Memset (VOID *pDst, UINT8 nV, UINT32 nlen) 


PARAMETERS 
Parameter Type In/Out Description 
pDst VOID * Out Array Pointer of destination data to be copied 
nv UINT8 In Value to be set 
nLen UINT32 In Length to be set 
RETURN VALUE 
None 
REMARKS 


This function is a mandatory ANSI function. ANSI function is implemented to map 
one-to-one with the standard ANSI function. 


This function is called by the function that wants to set the source buffer’s own data. 


EXAMPLE 


| #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


| VOID 
i Example (VOID) 
| { 
UINT8 *pBuf = (UINT8 *)OAM Malloc(512); 


j OAM Memset (pBuf, OxFF, (512)); 
|} 


(2) Example to implement the function in Symbian 
| VOID i 


| OAM_Memset (VOID *pSrc, UINT8 nV, UINT32 nLen) 

if 

I memset ((TAny*) (pSrc), (TInt) (nV), (unsigned int) (nLen)); 
3 


SEE ALSO 
OAM _Memcpy, OAM _Memcmp 
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OAM_Memcmp 


DESCRIPTION 
This function compares data of two buffers. 
SYNTAX 


INT32 
OAM _Memcmp (VOID *pBufl, VOID *pBuf2, UINT32 nlLen) 


PARAMETERS 

Parameter Type In/Out Description 

pBufl VOID * In Pointer of Buffer1 

pBuf2 VOID * In Pointer of Buffer2 

nLen UINT32 In Length to be compared 
RETURN VALUE 

Return Value Description 

Negative number When pBuf1 issmallerthan pBuf2. 

0 When pBufl isthe sameas pBuf2. 

Positive number When pBuf1 is bigger than pBuf2. 
REMARKS 


This function is a mandatory ANSI function. ANSI function is implemented to map 
one-to-one with the standard ANSI function. 


This function is called by the function that wants to compare data of two buffers. 


EXAMPLE 


i #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function 


| VOID 

| Example (VOID) 
| { 
| UINT8 Re; 

UINT8 *pBufl (UINT8 *)OAM Malloc(512) 
UINT8 *pBuf2 = (UINT8 *)OAM Malloc(512) 


NeoNe 


Re = OAM _Memcmp (pBufl, pBuf2); 


if (Re != 0) 
{ 
printf(“ Compare fail(%x)\n™“, Re); 


} 
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(2) Example to implement the function in Symbian 


i: INT32 

| OAM_Mememp (VOID *pSrc, VOID *pDst, UINT32 nlen) 
1 { 

i INT8 *pS1 = (UINT8 *)pSrc; 

INT8 *pD1 = (UINT8 *)pDst; 


while (nLen--) 


{ 
if (*pS1 != *pp1) 
return (*pS1l - *pD1); 
pslt+t; 
pD1++; 
} 


return 0; 


SEE ALSO 
OAM _Memcpy, OAM _Memset 


XSR v1.5.1 Porting Guide 53 


SAMSUNG DOG Tai! 


averpeie ah liviled 


OAM_Debug 


DESCRIPTION 
This function is called when XSR prints messages such as error or debug or etc. 
SYNTAX 


VOID 
OAM _Debug(VOID *pFmt, ...) 


PARAMETERS 


Parameter Type In/Out Description 
pFmt VOID * In Data to be printed 


RETURN VALUE 
None 
REMARKS 
This function is recommended. 


EXAMPLE 


| #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


| VOID 

| Example (VOID) 

| { 

i OAM Debug(“Print debug message”) ; 
'} 


(2) Example to implement the fuinction in Win32 
| VOID i 
| OAM_Debug(VOID *pFmt, ...) 

if 

| static char aStr[4096]; 
va_list ap; 


va_start (ap, pFmt); 
vsprintf(aStr, (char *) pFmt, ap); 
printf (aStr); 


va_end (ap); 


SEE ALSO 
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OAM_CreateSM 


DESCRIPTION 
This function creates the semaphore. 
SYNTAX 


BOOL32 
OAM CreateSM(SM32 *pHandle) 


PARAMETERS 

Parameter Type In/Out Description 

pHandle SM32 * Out Handle of the semaphore to be created 
RETURN VALUE 

Return Value Description 

TRUE32 If this function creates the semaphore successfully, it 

returns TRUE32. 

FALSE32 Else it returns FALSE32. 

REMARKS 


This function is an optional semaphore function. 
This function is called by the function that wants to create the semaphore. 


XSR_ regards the number of the semaphore token as O after calling 
OAM_CreateSM() .Thus, when a user implements OAM_CreateSM(), a user should 
set the initial value of the semaphore token as 0. 


EXAMPLE 


| #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


| VOID 
| Example (VOID) 
SM32 nsSm; 


if (OAM_CreateSM (&(nSm)) == FALSE32) 
{ 
FVM_DBG_PRINT ( (TEXT ("OAM CreateSM Error\r\n"))); 
i} 


(2) Example to implement the function in pSOS ; 
| BOOL32 i 
/ OAM_CreateSM(SM32 *pHandle) 
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BOOL32 bRet = TRUE32; 


if (sm_create("XSRS", 
0, 
SM_LOCAL | SM_FIFO | SM_UNBOUNDED, 
(ULONG *)pHandle) != 0) 


bRet = FALSE32; 
} 


return bRet; 


SEE ALSO 
OAM DestroySM, OAM_AcquireSM, OAM_ReleaseSM 
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OAM_DestroySM 


DESCRIPTION 
This function destroys the semaphore. 
SYNTAX 


BOOL32 
OAM_DestroySM(SM32 nHandle) 


PARAMETERS 

Parameter Type In/Out Description 

nHandle SM32 In Handle of the semaphore to be destroyed 
RETURN VALUE 

Return Value Description 

TRUE32 If this function destroys the semaphore successfully, it 

returns TRUE32. 

FALSE32 Else it returns FALSE32. 

REMARKS 


This function is an optional semaphore function. 
This function is called by the function that wants to destroy the semaphore. 


EXAMPLE 


| #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


| VOID 
| Example (VOID) 
i SM32 nsSm; 


if (OAM_CreateSM (&(nSm)) == FALSE32) 
{ 

FVM_DBG_PRINT ( (TEXT ("OAM CreateSM Error\r\n"))); 
} 


j OAM_DestroySM(nSm) ; 
|} 


(2) Example to implement the function in pSOS ; 
| BOOL32 i 
| OAM_DestroySM(SM32 nHandle) 

if 

i BOOL32 bRet = TRUE32; 
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| if (sm_delete(nHandle) != 0) 
; { 
| bRet = FALSE32; 
| return bRet; 
L) 
SEE ALSO 


OAM _CreateSM, OAM AcquireSM, OAM _ReleaseSM 
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OAM_AcquireSM 


DESCRIPTION 
This function acquires the semaphore. 
SYNTAX 


BOOL32 
OAM_AcquireSM(SM32 nHandle) 


PARAMETERS 

Parameter Type In/Out Description 

nHandle SM32 In Handle of the semaphore to be acquired 
RETURN VALUE 

Return Value Description 

TRUE32 If this function acquires the semaphore successfully, it 

returns TRUE32. 

FALSE3 Else it returns FALSE32. 

REMARKS 


This function is an optional semaphore function. 
This function is called by the function that wants to acquire the semaphore. 


EXAMPLE 


(1) Example to call the function ; 


| #include <OAM.h> 
| #include <XSRTypes.h> 


| VOID 
| Example (VOID) 
i SM32 nsSm; 


if (OAM_CreateSM (&nSm) == FALSE32) 
{ 
FVM_DBG_PRINT ( (TEXT ("OAM CreateSM Error\r\n"))); 


} 
OAM _ReleaseSM(nSm) ; 


OAM AcquireSM(nSm) ; 
j OAM_ReleaseSM (nSm) ; 
hea 


(2) Example to implement the function in pSOS 
| BOOL32 i 
i OAM _AcquireSM(SM32 nHandle) 
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4 
SEE ALSO 


BOOL32 bRet 


(sm_p (nHandle, 


return bRet; 


0) != 0) 


OAM_CreateSM, OAM DestroySM, OAM _ReleaseSM 
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OAM_ReleaseSM 


DESCRIPTION 
This function releases the semaphore. 
SYNTAX 


BOOL32 
OAM _ReleaseSM(SM32 nHandle) 


PARAMETERS 

Parameter Type In/Out Description 

nHandle SM32 In Handle of the semaphore to be released 
RETURN VALUE 

Return Value Description 

TRUE32 If this function releases the semaphore successfully, it 

returns TRUE32. 

FALSE32 Else it returns FALSE32. 

REMARKS 


This function is an optional semaphore function. 
This function is called by the function that wants to release the semaphore. 


EXAMPLE 


(1) Example to call the function : 


| #include <OAM.h> 
| #include <XSRTypes.h> 


| VOID 
| Example (VOID) 
i SM32 nsSm; 


if (OAM_CreateSM (&(nSm)) == FALSE32) 
{ 
FVM_DBG_PRINT ( (TEXT ("OAM CreateSM Error\r\n"))); 


} 
OAM _ReleaseSM(nSm) ; 


OAM AcquireSM(nSm) ; 
j OAM_ReleaseSM (nSm) ; 
hea 


(2) Example to implement the function in pSOS 
| BOOL32 
' OAM_ReleaseSM(SM32 nHandle) 
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| { 
| BOOL32 bRet = TRUE32; 
if (sm_v(nHandle) != 0) 
{ 
| bRet = FALSE32; 
| } 
| return bRet; 
i} 
SEE ALSO 


OAM CreateSM, OAM DestroySM, OAM _AcquireSM 
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OAM_InitInt 


DESCRIPTION 
This function initializes the specified logical interrupt for NAND device. 
SYNTAX 


VOID 
OAM _InitInt (UINT32 nLogIntId) 


PARAMETERS 


Parameter Type In/Out Description 
nLogIntId UINT32 In Logical interrupt ID number 


RETURN VALUE 
None 
REMARKS 


This function is an optional interrupt function. 
Currently, this function is used for asynchronous operation. 


EXAMPLE 


| #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function : 


| #define INT_ID_NAND_0O (0) /* Interrupt ID : 1st NAND */ 
| VOID 

| Example (VOID) 

| { 


j OAM_InitInt (INT_ID_NAND_0O) ; 
i} 


(2) Example to implement the function in Symbian 


VOID 

| OAM_InitInt (UINT32 nLogIntId) 
| { 

| switch (nLogIntId) 

i { 

| case XSR_INT_ID_NAND_0: 
| iNANDInt = new TNandInterrupt; 
| break; 

default: 

| break; 

i } 

| } 
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SEE ALSO 
OAM_BindInt, OAM_EnableInt, OAM_DisableInt, OAM_ClearInt 
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OAM_Bindint 


DESCRIPTION 
This function binds the specified interrupt for NAND device. 
SYNTAX 


VOID 
OAM BindInt (UINT32 nLogIntId, UINT32 nPhyIntId) 


PARAMETERS 
Parameter Type In/Out Description 
nLogIntId UINT32 In Logical interrupt ID number 
nPhyIntId UINT32 In Physical interrupt ID number 
RETURN VALUE 
None 


REMARKS 


This function is an optional interrupt function. 
Currently, this function is used for asynchronous operation. 


EXAMPLE 


i #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


| #define INT_ID_NAND_0O (0) /* Interrupt ID : lst NAND */ 


| enum TPlatformiInterruptiId 
if 


EIrgExt0, // IRQ 0 
EIrgExtl, // IRQ 1 
EIrgExt2, // IRQ 2 
EIrgExt3, // IRQ 3 
EIrgExt4_7, // IRQ 4 
EIrgExt8_23, // IRQ 5 
EIrqCAM, // IRQ 6 
EIrqBatteryFault, // IRQ 7 
EIrqTick, // IRQ 8 
ElIrqwatchdog, // IRQ 9 
EIrqTimer0, // IRQ 10 
EIrqTimerl, // IRQ 11 
EIrgTimer2, // IRQ 12 


|}; 
| VOID 


| Example (VOID) 
i { 
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OAM_BindInt (INT_ID_NAND_0, EIrqExt4_7); 


(2) Example to implement the function in Symbian 
| VOID 
| OAM_BindInt (UINT32 nLogIintId, UINT32 nPhyIntId) 
if 
| switch (nLogIntId) 
{ 
| case XSR_INT_ID_NAND_O: 
| iNANDInt->Bind((TInt)nPhyIntId, NandIsr, iNANDInt); | 
| break; i 
default: 
| break; 
} 
i} 

SEE ALSO 


OAM_InitInt, OAM_EnableInt, OAM_DisableInt, OAM_ClearInt 
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OAM_Enableint 


DESCRIPTION 
This function enables the specified interrupt for NAND device. 
SYNTAX 


VOID 
OAM_EnableInt (UINT32 nLogIntId, UINT32 nPhyIntId) 


PARAMETERS 
Parameter Type In/Out Description 
nLogIntId UINT32 In Logical interrupt ID number 
nPhyIntId UINT32 In Physical interrupt ID number 
RETURN VALUE 
None 


REMARKS 


This function is an optional interrupt function. 
Currently, this function is used for asynchronous operation. 


EXAMPLE 


i #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


| #define INT_ID_NAND_0O (0) /* Interrupt ID : lst NAND */ 


| enum TPlatformiInterruptiId 
if 


EIrgExt0, // IRQ 0 
EIrgExtl, // IRQ 1 
EIrgExt2, // IRQ 2 
EIrgExt3, // IRQ 3 
EIrgExt4_7, // IRQ 4 
EIrgExt8_23, // IRQ 5 
EIrqCAM, // IRQ 6 
EIrqBatteryFault, // IRQ 7 
EIrqTick, // IRQ 8 
ElIrqwatchdog, // IRQ 9 
EIrqTimer0, // IRQ 10 
EIrqTimerl, // IRQ 11 
EIrgTimer2, // IRQ 12 


|}; 
| VOID 


| Example (VOID) 
i { 
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OAM EnableInt (INT_ID_NAND_0O, EIrgqExt4_7); 


(2) Example to implement the function in Symbian 
| VOID i 
| OAM_EnableInt (UINT32 nLogIntId, UINT32 nPhyIntId) 
if 
| switch (nLogIntId) 
i { 
| case XSR_INT_ID_NAND_O: 
| iNANDInt->Enable( (TInt) nPhyIntIq) ; 
| break; 
| default: 
| break; 
i} 
SEE ALSO 


OAM_InitInt, OAM _BindInt, OAM_DisableInt, OAM_ClearInt 
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OAM_Disableint 


DESCRIPTION 
This function disables the specified interrupt for NAND device. 
SYNTAX 


VOID 
OAM_DisableInt (UINT32 nLogIntId, UINT32 nPhyIntId) 


PARAMETERS 
Parameter Type In/Out Description 
nLogIntId UINT32 In Logical interrupt ID number 
nPhyIntId UINT32 In Physical interrupt ID number 
RETURN VALUE 
None 


REMARKS 


This function is an optional interrupt function. 
Currently, this function is used for asynchronous operation. 


EXAMPLE 


i #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


| #define INT_ID_NAND_0O (0) /* Interrupt ID : lst NAND */ 


| enum TPlatformiInterruptiId 
if 


EIrgExt0, // IRQ 0 
EIrgExtl, // IRQ 1 
EIrgExt2, // IRQ 2 
EIrgExt3, // IRQ 3 
EIrgExt4_7, // IRQ 4 
EIrgExt8_23, // IRQ 5 
EIrqCAM, // IRQ 6 
EIrqBatteryFault, // IRQ 7 
EIrqTick, // IRQ 8 
ElIrqwatchdog, // IRQ 9 
EIrqTimer0, // IRQ 10 
EIrqTimerl, // IRQ 11 
EIrgTimer2, // IRQ 12 


|}; 
| VOID 


| Example (VOID) 
i { 
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OAM DisableInt (INT_ID_NAND_0, EIrqExt4_7); 


(2) Example to implement the function in Symbian 
| VOID i 
| OAM_DisableInt (UINT32 nLogIntId, UINT32 nPhyIntId) 
| { 
| switch (nLogIntId) 
{ 
| case XSR_INT_ID_NAND_O: 
| iNANDInt->Disable((TInt)nPhyIntId) ; 
| break; 
| default: 
| break; 
i} 
SEE ALSO 


OAM_InitInt, OAM _BindInt, OAM_EnableInt, OAM _ClearInt 
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OAM_ClearInt 


DESCRIPTION 
This function clears the specified interrupt for NAND device. 
SYNTAX 


VOID 
OAM_ClearInt (UINT32 nLogIntId, UINT32 nPhyIntId) 


PARAMETERS 
Parameter Type In/Out Description 
nLogIntId UINT32 In Logical interrupt ID number 
nPhyIntId UINT32 In Physical interrupt ID number 
RETURN VALUE 
None 


REMARKS 


This function is an optional interrupt function. 
Currently, this function is used for asynchronous operation. 


EXAMPLE 


i #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


| #define INT_ID_NAND_0O (0) /* Interrupt ID : lst NAND */ 


| enum TPlatformiInterruptiId 
if 


EIrgExt0, // IRQ 0 
EIrgExtl, // IRQ 1 
EIrgExt2, // IRQ 2 
EIrgExt3, // IRQ 3 
EIrgExt4_7, // IRQ 4 
EIrgExt8_23, // IRQ 5 
EIrqCAM, // IRQ 6 
EIrqBatteryFault, // IRQ 7 
EIrqTick, // IRQ 8 
ElIrqwatchdog, // IRQ 9 
EIrqTimer0, // IRQ 10 
EIrqTimerl, // IRQ 11 
EIrgTimer2, // IRQ 12 


[i 


| VOID 
i Example (VOID) 
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OAM ClearInt (INT_ID_NAND_0O, EIrqExt4_7)j; 


(2) Example to implement the function in Symbian 


| VOID 
| OAM_ClearInt (UINT32 nLogIintId, UINT32 nPhyIntId) 
I { 
i switch (nLogIntId) 
i { 
| case XSR_INT_ID_NAND_O: 
| iNANDInt->Clear ( (TInt) nPhyIntId) ; 
| break; 
default: 
| break; 
| } 
i} 
SEE ALSO 


OAM_InitInt, OAM _BindInt, OAM _EnableInt, OAM _DisableInt 
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OAM_ResetTimer 


DESCRIPTION 
This function resets the timer. 


SYNTAX 


VOID 
OAM _ResetTimer (VOID) 


PARAMETERS 


None 


RETURN VALUE 


None 


REMARKS 


This function is a recommended timer function. 
Currently, this function is used for asynchronous operation. 


In current implementation, this function does not use a timer of operating system but uses 
global counter variables. However, if user wants to implement the asynchronous feature 
based on execution time of operation, this function should be changed to use the real OS 
timer instead of the counter. 


For more information about timer functions for asynchronous feature, refer to 7.2.5 Timer. 


EXAMPLE 


: #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


| VOID 

| Example (VOID) 

ie 

i OAM_ResetTimer () ; 
3 


| static UINT32 nTimerCounter = 0; 
i static UINT16 nTimerPrevCnt = 0; 


(2) Example to implement the function in Symbian 


| VOID 


| OAM_Reset Timer (VOID) 
E 

i nTimerPrevCnt = 0; 
| nTimerCounter = 0; 
|} 
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SEE ALSO 
OAM_GetTime, OAM _WaitNMSec 
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OAM_GetTime 


DESCRIPTION 


This function returns the current time value. 


SYNTAX 


UINT32 
OAM_Get Time (VOID) 


PARAMETERS 
None 
RETURN TYPE 
“Return Type ——————SDeseription ss 
UINT32 Current time value 
REMARKS 


This function is a recommended timer function. 
Currently, this function is used for asynchronous operation. 


In current implementation, this function does not use a timer of operating system but uses 
global counter variables. However, if user wants to implement the asynchronous feature 
based on execution time of operation, this function should be changed to use the real OS 
timer instead of the counter. 


For more information about timer functions for asynchronous feature, refer to 7.2.5 Timer. 


EXAMPLE 


i #include <OAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function : 


| VOID 

| Example (VOID) 

| { 

i UINT32 nStartTime; 


nStartTime = OAM _GetTime(); 


(2) Example to implement the function in Symbian 
| UINT32 I 
| OAM_Get Time (VOID) 

if 

; return nTimerCountertt+; 
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SEE ALSO 
OAM ResetTimer, OAM WaitNMSec 
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OAM_WaitNMSec 


DESCRIPTION 
This function is called for waiting as a unit of milliseconds. 
SYNTAX 


VOID 
OAM_WaitNMSec (UINT32 nNMSec) 


PARAMETERS 


Parameter Type In/Out Description 
nNMSec UINT32 In usec time for waiting 


RETURN TYPE 
None 
REMARKS 


This function is a recommended timer function. 
Currently, this function is used to wait the time in handling Power-off error. 


For more information about timer functions for power-off recovery, refer to 7.3 Power-Off 
Recovery. 


EXAMPLE 


(1) Example to implement the function in Win32 
/ VOID i 
| OAM WaitNMSec (UINT32 nNMSec) 

if 

| Sleep (nNMSec) ; 

i} 


SEE ALSO 
OAM ResetTimer, OAM _GetTime 
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OAM_Pa2Va 


DESCRIPTION 


This function is called for the address translation to access to the hardware from the system 
using virtual memory. 


SYNTAX 


UINT32 
OAM_Pa2Va(UINT32 nPAddr) 


PARAMETERS 

Parameter Type In/Out Description 

nPAddr UINT32 In Physical address of NAND device 
RETURN TYPE 

Return Type Description 

UINT32 Virtual address of NAND device that Symbian OS uses 
REMARKS 


This function is recommended. 


EXAMPLE 


(1) Example to call the function ; 


i #include <OAM.h> 
| #include <XSRTypes.h> 


| VOID 

| Example (VOID) 

if 

i INT32 nBaseAddr = 0x30000000; 
UINT32 nVirtualAddr; 


nVirtualAddr = OAM Pa2Va(nBaseAddr) ); 


| UINT32 
i OAM Pa2Va(UINT32 nPAddr) 
i{ 


(2) Example to implement the function in Symbian 


DPlatChunkHw *NandChunk; 
TLinAddr NandVirtAddr; 


XSR_DBG_PRINT ( (TEXT (">Nand: :Open -> OneNandPhyAddr = 0x%x"), | 
nPAddr) ); i 


TInt r=DPlatChunkHw: :New (NandChunk, nPAddr, 0x80000, 
EMapAtt rSupRw |EMapAttrFullyBlocking) ; 
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if (r != KErrNone) 
{ 
XSR_DBG_PRINT ( (TEXT (">Nand::Open -> NandChunk-> 
DoCreateL failed = Ox%x"), r)); 
return r; 


} 


NandVirtAddr = NandChunk->LinearAddress(); 
XSR_DBG_PRINT ( (TEXT (">Nand::Open -> OneNandVirtAddr 
= 0Ox%x"), NandVirtAddr) ); 


return (UINT32) NandVirtAddr; 


SEE ALSO 
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OAM Idle 


DESCRIPTION 
This function is called when XSR is at idle time. 
SYNTAX 


VOID 
OAM_ Idle (VOID) 


PARAMETERS 
None 
RETURN TYPE 
None 
REMARKS 
This function is optional. 
If XSR is polling on the device status, this function is called. 
XSR usually keep polling on device status register to perform next operation. This polling 
takes little time, so ,usually, this function is not needed.to implement. But, under certain 
condition, it is better to yield CPU to other task instead of just waiting. XSR performance 
will be decreased, but other task can be performed with XSR simultaneously. 


Caution : Do not perform any flash memory operation (XSR operation) in this function. 


EXAMPLE 


(1) Example to implement the function in Symbian 
| VOID i 
| OAM_Idle (VOID) 

| { 
| /* Default : Do nothing */ 
|} 


SEE ALSO 
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OAM_GetROLockFlag 


DESCRIPTION 
This function is called when XSR determines Read Only attribute. 
SYNTAX 


BOOL32 
OAM _GetROLockFlag (VOID) 


PARAMETERS 
None 
RETURN TYPE 
“ReturnType————SDeseiption 
BOOL32 TRUE32 with RO partition. 
REMARKS 


This function is optional. 


The function OAM_GetROLockFlag is called when XSR determines whether certain block 
is in Read-Only partition or not. If XSR finds it is in range of RO partition, this function is 
called. If it is necessary to regard blocks in RO partition as RW under certain condition, 
implement this function to return FALSE. Do not modify this function unless you deeply 
understand internal implementation of XSR. Default implementation of this function just 
returns TRUE. 


When the RO partition should be regarded as RW, this function should return FALSE. 


EXAMPLE 


(1) Example to implement the function in Symbian 
| BOOL32 i 
| OAM_Get ROLockF lag (VOID) 

Ia 

return TRUE32; 

|} 


SEE ALSO 
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J. 


ol: 


LLD (Low Level Driver) 


This chapter describes the definition, system architecture, features, and APIs of LLD. 


Description & Architecture 


LLD is an abbreviation of Low Level Device Driver. LLD is adaptation module of XSR. 
LLD accesses the real device. 


XSR cannot send a command directly to the device. When XSR sends a command to the 
device, it is needed a kind of translator, converting XSR command to the 
device-understandable message. The translator is a device driver LLD. LLD directly access 
to the device. 


@ Reference 


Generally, a device is a machine or hardware designed for a purpose. For example, it can 
include keyboards, mouse, display monitors, hard disk drives, CD-ROM players, printers, 
audio speakers, and etc. In this document, a device means NAND flash memory. 


Generally, a device driver is a program that controls a particular type of a device. That is, a 
device driver converts the general input/output instruction of the Operation system to 
messages that the device type can understand. 


For example, if XSR orders “read” command to the device, the device cannot receive 
“read” command of XSR itself. LLD translates “read” command for the device. Thus, the 
device receives “read” command not by XSR but by LLD, and executes it. Therefore, a user 
must implement LLD suitable for the device when a user ports XSR. 


Figure 5-1 shows LLD in XSR system architecture. 
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File System 
| 


Block Device Interface 


Logical Flash Address 


XSR Core 


OS Adaptation 
Module 


Sector Translation Layer 


| Virtual Flash Address 
Platform Adaptation 


Block Management Layer Module 


Physical Flash Address 


NAND Flash Memory 


Figure 5-1. LLD in XSR System Architecture 


LLD has 17 functions that are classified into 6 categories as follows. 
0 Initialization functions : initialization, open, and close 

O Device information query function : device information return 
0 Flash operation function : read, write, and erase 

O Copyback function : copyback 

QO Other functions : initial bad block check, writable area setting 


QO Deferred Check Operation functions 


In the next chapter, LLD APIs are covered in detail. 
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5.2. API 


This chapter describes LLD APIs. 


= Note 
In Table 5-1, a user can rename XXX in the function name. It is recommended to name 
XXX with the device name and three or four capital letters. 


Table 5-1 shows the lists of LLD APIs. 

The right row in table shows that the function is Mandatory or Optional or Recommended. 
Optional functions should be existed, but contents of the functions does not need to be 
implemented. 


Table 5-1. LLD API 


Function Description 

XXX_Init This function initializes the device driver. M 

XXX_Open This function opens the device and makes it be ready. M 

XXX_Close This function closes the device and closes linking. M 

XXX_GetDevinfo This function reports the device information to upper M 
layer. 

XXX_Read This function reads data from a page of NAND flash M 
memory within page boundry. 

XXX_Write This function writes data into a page of NAND flash M 
memory page boundry. 
XXX_Erase This function erases a block of NAND flash memory. M 
XXX_MRead This function reads data from a page of NAND flash M 
memory within block boundary. 
XXX_MWrite This function writes data into a page of NAND flash M 
memory within block boundary. 
XXX_MErase This function erases multiple blocks of NAND flash M 
memory 

XXX_EraseVerify This function verifies an erase operation whether M 
success or not 

XXX_CopyBack This function copies data by using internal buffer in the | M 
device. 

XXX_ChkInitBadB1k | This function checks whether a block is an initial bad M 
block or not. 

XXX_SetRWArea This function is called when NAND device provides O 
write/erase protection functionality in hardware. 

XXX_Ioctl This function is called to extend LLD functionality. O 

XXX_GetPrevOpData | This function copies data of previous write operation to | O 
the given buffer. 

XXX_FlushOp This function completes the current working operation. | O 
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XXX_Init 


DESCRIPTION 
This function initializes XXX device driver. 


SYNTAX 


INT32 
XXX_Init (VOID *pParm) 


PARAMETERS 

Parameter Type In/Out Description 

pParm VOID * In Pointer to XsrVolParm data structure 
RETURN VALUE 

Return Value Description 

LLD_SUCCESS Initialize Success 

LLD_INIT_FAILURE Initialize Failure 
REMARKS 


This function is a mandatory initialization function. 


For more information about XsrVolParm data structure, refer to the API page of 
PAM GetPAParm. 


EXAMPLE 


(1) Example to call the function 


: #include <XSRTypes.h> 

: #include <PAM.h> 

| #include <LLD.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver */ | 


| BOOL32 
| Example (VOID) 
int 


INT32 nErr; 
UINT32 nVol = 0; 
UINT32 nBaseAddr = 0x20000000; 


LowFuncTbl stLFT[MAX_VOL]; 


PAM _RegLFT( (VOID *)stLFT); 
nErr = stLFT[nVol].Init((VOID *) PAM _GetPAParm()); 


if (nErr != LLD_SUCCESS) 
{ : 
printf (“XXX_Init ($d) fail. ErrCode = %x\n”, nDev, nErr); | 
return (FALSE32) ; i 
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return (TRUE32); 


| INT32 
| ONLD_Init (VOID *pParm) 
| { 


(2) Example to implement the function in OneNAND 


UINT32 nCnt; 

UINT32 nidx; 

UINT32 nVol; 

static BOOL32 nInitFlg = FALSE32; 
XsrvolParm *pstParm = (XsrVolParm*) pParm; 


ONLD_DBG_PRINT((TEXT("([ONLD : IN] ++ONLD_Init()\r\n"))); 


if (nInitFlg == TRUE32) 
{ 

return (ONLD_SUCCESS) ; 
} 


for (nCnt = 0; nCnt < MAX_SUPPORT_DEVS; nCnt++) 
{ 


pstPrevOpInfo[nCnt ] = (PrevOpiInfo *) NULL; 
astONLDDev [nCnt] .bOpen = FALSE32; 
astONLDDev[nCnt] .bPower = FALSE32; 


astONLDDev[nCnt].pstDevSpec = NULL; 
} 


for (nVol = 0; nVol < XSR_MAX_ VOL; nVol++t) 
{ 
for (nIdx = 0; nIdx < (XSR_MAX_DEV / XSR_MAX_VOL) ; nIdx++) 
{ 
nCnt = nVol * (XSR_MAX DEV / XSR_MAX VOL) + nIdx; 


if (pstParm[nVol] .nBaseAddr[nIdx] != NOT_MAPPED) 


astONLDDev [nCnt] .BaseAddr 
= OAM Pa2Va(pstParm[nVol] .nBaseAddr [nIdx]); 


else 
astONLDDev [nCnt] .BaseAddr = NOT_MAPPED; 
} 
ninitFlg = TRUE32; 


ONLD_DBG_PRINT((TEXT("([ONLD : OUT] --ONLD_Init()\r\n"))); 


return (ONLD_SUCCESS) ; 


SEE ALSO 
XXX_Open, XXX_Close 
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XXX_Open 


DESCRIPTION 
This function opens the device and makes it be ready. 
SYNTAX 


INT32 
XXX_Open (UINT32 nDev) 


PARAMETERS 

Parameter Type In/Out Description 

nDev UINT32 In Physical Device Number (0 ~ 7) 
RETURN VALUE 

Return Value Description 

LLD_SUCCESS Open Success 

LLD_OPEN_FATLURE Open Failure 
REMARKS 


This function is a mandatory initialization function. 


EXAMPLE 


(1) Example to call the function 
| #include <XSRTypes.h> | 
| #include <PAM.h> i 
| #include <LLD.h> 


| #include <XXX.h> /* Header File of Low Level Device Driver fe 


| BOOL32 


| Example (VOID) 

| 

i INT32 nErr; 
UINT32 nDev = 0; 
UINT32 nVol = 0; 


LowFuncTbl stLFT[MAX_VOL]; 
PAM RegLFT( (VOID *)stLFT); 
nErr = stLFT[nVol] .Open (nDev) ; 


if (nErr != LLD_SUCCESS) 
{ i 
printf (“XXX_Open(%d) fail. ErrCode = %x\n”, nDev, nErr); | 
return (FALSE32); i 


} 
return (TRUE32); 
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(2) Example to implement the function in OneNAND 
| INT32 i 


| ONLD_Open (UINT32 nDev) 
if 

i INT32 nCnt; 

UINT16 nMID, nDID, nVID; 
UINT32 nBAddr; 
LLDMEArg *pstMEArg; 


SET_PWR_FLAG (nDev) ; 


_GetDevID(nDev, &nMID, &nDID, &nVID); 


for (nCnt = 0; astNandSpec[nCnt].nMID != 0; nCnt++t) 
{ 
if (nDID == astNandSpec[nCnt].nDID) 
{ 
if ((nVID >> 8) == astNandSpec[nCnt] .nGEN) 
{ 
astONLDDev [nDev] .bOpen = TRUE32; | 
astONLDDev [nDev] .pstDevSpec = &astNandSpec[nCnt]; | 
break; i 
} 
else 
{ 
continue; 


} 


} 
_InitDeviInfo(nDev, &nDID, &nVID); 


if (astONLDDev[nDev].bOpen != TRUE32) 
{ 

CLEAR_PWR_FLAG (nDev) ; 

return (ONLD_OPEN_FATLURE) ; 


if (pstPrevOpInfo[nDev] == (PrevOpInfo*) NULL) 


pstPrevOpInfo[nDev] 
= (PrevOpInfo*) MALLOC (sizeof (PrevOpInfo) ); 


if (pstPrevOpInfo[nDev] == (PrevOpInfo*) NULL) 
{ 
return (ONLD_OPEN_FATLURE) ; 
} 
} 


pstPrevOpInfo [nDev] ->ePreOp = NONE; 
pstPrevOpInfo [nDev] ->nCmd = 0; 
pstPrevOpInfo[nDev]-—->nPsn = 0; 
pstPrevOpInfo[nDev]->nScts = 0; 
pstPrevOpInfo [nDev] ->nFlag = 0; 


pstPrevOpInfo[nDev]->pstPreMEArg 
= (LLDMEArg*) MALLOC (sizeof (LLDMEArg) ) ; 
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pstMEArg = pstPrevOpInfo[nDev] ->pstPreMEArg; 
if (pstMEArg == NULL) 
{ 

return (ONLD_OPEN_FAILURE) ; 


MEMSET (pstMEArg, 0x00, sizeof (LLDMEArg) ); 
pstMEArg->pstMEList 
= (LLDMEList*) MALLOC (sizeof (LLDMEList) * XSR_MAX MEBLK) ; 
if (pstMEArg->pstMEList == NULL) 
{ 
return (ONLD_OPEN_FAILURE) ; 


pstMEArg-—>nNumOfMList = (UINT16) 0x00; 
pstMEArg->nBitMapErr = (UINT16) 0x00; 
pstMEArg->bFlag = FALSE32; 


pstPrevOpInfo[nDev]-—>nBufSel = DATA_BUFO; 
nBAddr = GET_DEV_BADDR (nDev) ; 


/* IO Buffer Enable for NAND interrupt enable/disable */ 
ONLD_REG_SYS_CONF1(nBAddr) &= MASK _SYNC_BURST_READ; 
ONLD_REG_SYS_CONF1 (nBAddr) = 

(IOBE_ENABLE | BST_RD_LATENCY_4 BST_LENGTH_8WD) ; 


ONLD_REG_SYS_CONF'1 (nBAddr) l= (SYNC_READ_MODE) ; 
j LLD_RTL_PRINT ( (TEXT ("[ONLD:MSG] nNumOfBlks = Sd\r\n"), 
| astONLDDev [nDev] .pstDevSpec->nNumOfB1ks) ) ; 
| LLD_RTL_PRINT ( (TEXT ("[ONLD: MSG] nNumOfPlanes = %d\r\n"), 
: astONLDDev [nDev] .pstDevSpec—>nNumOfPlanes) ); 
i LLD_RTL_PRINT ( (TEXT ("[ONLD: MSG] nBlksInRsv = $d\r\n"), 
| astONLDDev [nDev] .pstDevSpec->nBlksInRsv) ); 
LLD_RTL_PRINT ( (TEXT ("[ONLD: MSG] nBadPos = $d\r\n"), 
| aStONLDDev [nDev] .pstDevSpec->nBadPos) ) ; 
: LLD_RTL_PRINT ( (TEXT ("[ONLD:MSG] nLsnPos = $d\r\n"), 
| astONLDDev [nDev] .pstDevSpec->nLsnPos) ) ; 
LLD_RTL_PRINT ( (TEXT ("[ONLD: MSG] nECCPos = Sd\r\n"), 
| aStONLDDev [nDev] .pstDevSpec->nEccPos) ) ; 
| LLD_RTL_PRINT ( (TEXT ("([ONLD: MSG] nBWidth = $d\r\n"), 
: astONLDDev [nDev] .pstDevSpec-—>nBWidth) ); 
| LLD_RTL_PRINT ( (TEXT ("[ONLD: MSG] nMEFlag = $d\r\n"), 
| astONLDDev [nDev] .pstDevSpec->nMEF lag) ) ; 
| LLD_RTL_PRINT ( (TEXT ("[ONLD: MSG] nLKFlag = Sd\r\n"), 


| astONLDDev [nDev] .pstDevSpec->nLKF lag) ) ; 


return (ONLD_SUCCESS) ; 


SEE ALSO 
XXX_Init, XXX_Close 
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XXX_Close 


DESCRIPTION 
This function closes XXX device and closes linking. 
SYNTAX 


INT32 
XXX_Close (UINT32 nDev) 


PARAMETERS 

Parameter Type In/Out Description 

nDev UINT32 In Physical Device Number (0 ~ 7) 
RETURN VALUE 

Return Value Description 

LLD_SUCCESS Close Success 

LLD_CLOSE_FATLURE Close Failure 
REMARKS 


This function is a mandatory initialization function. 


EXAMPLE 


(1) Example to call the function, 
| #include <XSRTypes.h> | 
| #include <PAM.h> 
i #include <LLD.h> 


| #include <XXX.h> /* Header File of Low Level Device Driver at 


| BOOL32 


| Example (VOID) 

if 

; INT32 nErr; 
UINT32 nDev = 0; 
UINT32 nVol = 0; 


LowFuncTbl stLFT[MAX_VOL]; 
PAM RegLFT((VOID *)sStLFT); 
nErr = stLFT[nVol].Close(nDev) ; 


if (nErr != LLD_SUCCESS) 
{ i 
printf (“XXX_Close(%d) fail. ErrCode = %x\n”, nDev, nErr); | 
return (FALSE32) ; i 


} 
return (TRUE32); 
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(2) Example to implement the function in OneNAND 
| INT32 i 


| ONLD_Close (UINT32 nDev) 
lf 

| UINT32 nBAddr; 

INT32 nRes = ONLD SUCCESS; 


nBAddr = GET_DEV_BADDR (nDev) ; 


if ((nRes =ONLD_FlushOp(nDev)) != ONLD_SUCCESS) 
{ 
return nRes; 


} 
if (pstPrevOpInfo[nDev] != (PrevOpInfo*) NULL) 


FREE (pst PrevOpInfo [nDev]—->pstPreMEArg->pstMEList) ; 
pstPrevOpInfo [nDev] ->pstPreMEArg->pstMEList 

= (LLDMEList*) NULL; 
FREE (pstPrevOpInfo[nDev]-—->pstPreMEArg) ; 
pstPrevOpInfo[nDev]->pstPreMEArg = (LLDMEArg*) NULL; 


FREE (pstPrevOpInfo[nDev]); 
pstPrevOpiInfo[nDev] = (PrevOpInfo*) NULL; 


} 


astONLDDev [nDev] .bOpen = FALSE32; 
astONLDDev [nDev] .bPower = FALSE32; 
astONLDDev [nDev].pstDevSpec = NULL; 


return (ONLD_SUCCESS) ; 


SEE ALSO 
XXX_Init, XXX_Open 
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XXX_GetDevinfo 


DESCRIPTION 
This function reports the device information to upper layer. 
SYNTAX 


INT32 
XXX_GetDeviInfo(UINT32 nDev, LLDSpec* pstDeviInfo) 


PARAMETERS 
Parameter Type In/Out Description 
nDev UINT32 In Physical Device Number (0 ~ 7) 
pstDeviInfo LLDSpec* Out Data structure of device information 
RETURN VALUE 
Return Value Description 
LLD_SUCCESS Sending the requested information 
LLD_ILLEGAL_ACCESS Illegal Access 
REMARKS 


This function is a mandatory device information query function. 


LLDSpec data structure is declared in LLD -h. 


O1LLDSpec data structure 


_ typedef struct { /* offset size */ 
i UINT8 nMCode; /* Manufacturer Code 0x00 1 */ 
UINTS8 nDCode; /* Device Code 0x01 1 */ 


UINT16 nNumOfBlks; /* The Number of Blocks 0x02 2 */ 
UINT16 nPgsPerBlk; /* The Number of Pages per Block 
0x04 2 */ 
UINT16 nBlksInRsv; /* The Number of Blocks 0x06 2 

in Reserved Block Pool * / 
UINT8 nSctsPerPg; /* The Number of Sectors per Page 
0x08 1 */ 
UINT8 nNumOfPlane; /* The Number of Plane 0x09 1 */ 


UINT8 nMEFlag; /* Multi-block Erase Flag 0x0A 1 */ 
UINT8 nBWidth; /* Device Bus Width Ox0C 1 */ 
UINT8 nBadPos; /* BadBlock Information Position 
Ox0E 1 */ 
UINT8 nLsnPos; /* LSN Position Ox0E 1 */ 
UINT8 nEccPos; /* ECC Value Position Ox0F 1 */ 
UINT8 aUID[XSR_UID_SIZE]; /* UID 0x10 16, 
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OxFF (absence case of UID) */ 


ye 
*/ 
*/ 


UINT16 nTrTime; /* Physical Read Operation Time 0x20 2 

UINT16 nTwTime; /* Physical Write Operation Time 0x22 2 

UINT16 nTeTime; /* Physical Erase Operation Time 0x24 2 
i UINT16 nTfTime; /* Data Transfer Time Ox26 2 
i} LLDSpec; 


Table 5-2 explains LLDSpec data structure. 
Table 5-2. LLDSpec in LLD.h 


Member Variable Member Variable 

nMCode Manufacturer code of a device 

nDCode Device code 

nNumOfBlks Total number of blocks of a device 
nPgsPerBlk The number of pages per one block of a device 
nBlksInRsv The number of blocks in reserved block pool 
nSctsPerPg The number of sectors per one page of device 
nNumOfPlane The number of planes of a device 

nMEF lag Flag for multi-block erase 

nBWidth Device bus width 

nBadPos Bad block information position 

nLsnPos Position to store LSN 

nECCPos Position to store ECC value 

aUID Unique ID of device 

[XSR_UID_SIZE] 

nTrTime Physical read operation time of a device (nsec) 
nTwTime Physical write operation time of a device (nsec) 
nTeTime Physical erase operation time of a device (nsec) 
nTfTime Data transfer time of a device (nsec) 


Here is more detailed explanation about LLDSpec. 


O nBlksiInRsv 

In general, NAND flash memory can contain bad block. nB1ksInRsv is the number of the 
reserved block in NAND flash memory. The related information about the number of the 
reserved block is described in “VALID BLOCK” chapter inside data sheet of flash memory. 
In VALID BLOCK chapter, the maximum valid block number and the minimum valid 
block number is marked. nBlksInRsv is the remainder between the maximum valid 
block number and the minimum valid block number. 


O nNumOfPlane 
nNumOfP lane is the number of planes in NAND flash memory. NAND flash memory can 
consists of one or more planes internally. 


O nMEFlag 

nMEF lag means whether NAND flash memory support multi-block erase functionality or 
not. If NAND flash memory supports multi-block erase, nMEF lag can have LLD_ME_OK 
or LLD_ME_NO. However, NAND flash memory does not support multi-block erase, 
nMEF lag must have LLD_ME_NO. (For more information about which device supports 
multi-block erase, refer to the Specification of NAND flash memory.) 
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O nBWidth 

nBWidth is the data bus width in NAND flash memory. The data bus of NAND flash 
memory can be 8bit or 16bit. If the data bus is 8bit, nBWidth becomes LLD_BW_X08. If 
the data bus is 16bit, nBWidth becomes LLD_BW_X16. 

This value is used at software ECC module in BML. If this value is abnormal, the return 
value of software ECC can be abnormal. 


O nBadPos 

To show a bad block, the blocks of NAND flash memory records the specific value at the 
specific position of spare array. nBadPos is offset of the bad block position of spare array. 
nBadPos depends on the kind of NAND flash memory. A user can know nBadPos in the 
data sheet of NAND flash memory or “Samsung NAND flash Spare Area Assignment 
Standard (21.Feb.2003)”. 


O nisnPos 

nLsnPos is offset that the first byte of LSN(Logical Sector Number) of spare array is 
located. 

nLsnPos depends on the kind of NAND flash memory. A user can know nLsnPos in the 
data sheet of NAND flash memory or “Samsung NAND flash Spare Area Assignment 
Standard (21.Feb.2003)”. 


O nEccPos 

nEccPos is offset that the first byte of ECC of spare array is located. 

nEccPos depends on the kind of NAND flash memory. A user can know nEccPos in the 
data sheet of NAND flash memory or “Samsung NAND flash Spare Area Assignment 
Standard (21.Feb.2003)”. 


EXAMPLE 


(1) Example to call the function 
i #include <XSRTypes.h> 
| #include <PAM.h> 

i #include <LLD.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver x/ | 


| BOOL32 
| Example (VOID) 
4 


INT32 nErr; 
UINT32 nDev = 0; 
UINT32 nVol = 0; 


LLDSpec stDevinfo; 
LowFuncTbl stLFT[MAX_VOL]; 


PAM RegLFT( (VOID *)stLFT); 
nErr = stLFT[nVol].GetDevinfo(nDev, &stDevInfo); 


if (nErr != LLD_SUCCESS) 

{ 
printf (“XXX_ GetDeviInfo() fail. ErrCode = %x\n"”, nErr); 
return (FALSE32); 

} 

return (TRUE32); 
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(2) Example to implement the function in OneNAND 
| INT32 i 


| ONLD_GetDevInfo (UINT32 nDev, LLDSpec *pstFILDev) 
i { 
! UINT32 nBAddr; 


if 
{ 


(astONLDDev [nDev].pstDevSpec == NULL) 


return (ONLD_ILLEGAL_ ACCESS) ; 


nBAddr = GET_DEV_BADDR (nDev) ; 

pstFILDev->nMCode 

= (UINT8) astONLDDev [nDev] .pstDevSpec-—>nMID; 
pstFILDev-—>nDCode 
= (UINT8) astONLDDev [nDev] .pstDevSpec-—>nDID; 
pstFILDev—->nNumOfBlks 
= (UINT16) astONLDDev [nDev] .pstDevSpec-—>nNumOfBlks; 
pstFILDev—->nPgsPerBlk = (UINT16) GET_PGS_PER_BLK (nDev) ; 
pstFILDev—->nBlksInRsv 
= (UINT16) astONLDDev [nDev] .pstDevSpec-—>nBlksInRsv; 


pstFILDev->nSctsPerPg = 
pstFILDev—->nNumOfPlane 


(UINT8) GET_SCTS_PER_PG (nDev) ; 


pstFILDev->nBadPos 


pstFILDev->nLsnPos 


pstFILDev->nEccPos 


pstFILDev->nBWidth 


pstFILDev—->nMEFlag 


= (UINT8) astONLDDev[nDev] .pstDevSpec—>nBadPos; 
= (UINTS8) astONLDDev[nDev] .pstDevSpec-—>nLsnPos; 
= (UINTS8) astONLDDev [nDev] .pstDevSpec—>nEccPos; 


= (UINT8) astONLDDev [nDev] .pstDevSpec—>nBWidth; 


= (UINTS8) astONLDDev [nDev] .pstDevSpec-—>nMEFlag; 


pstFILDev->aUID[0] = OxEC; 
pstFILDev->aUID[1] = 0x00; 
pstFILDev->aUID[2] = 0xC5; 
pstFILDev->aUID[3] = Ox5F; 
pstFILDev—->aUID[4] = 0x3D; 
pstFILDev->aUID[5] = 0x12; 
pstFILDev->aUID[6] = 0x34; 
pstFILDev->aUID[7] = 0x37; 
pstFILDev->aUID[8] = 0x34; 
pstFILDev->aUID[9] = 0x33; 
pstFILDev-—>aUID[10] = 0x30; 
pstFILDev->aUID[11] = 0x30; 
pstFILDev->aUID[12] = 0x03; 
pstFILDev->aUID[13] = 0x03; 
pstFILDev-—>aUID[14] = 0x06; 
pstFILDev-—>aUID[15] = 0x02; 
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pstFILDev->nTrTime 
= (UINT32) astONLDDev [nDev] .pstDevSpec-—>nTrTime; 
pstFILDev->nTwTime 
= (UINT32) astONLDDev [nDev] .pstDevSpec—>nTwTime; 
pstFILDev->nTeTime 
= (UINT32) astONLDDev [nDev] .pstDevSpec-—>nTeTime; 
pstFILDev->nTfTime 
= (UINT32) astONLDDev [nDev] .pstDevSpec-—>nTfTime; 


return (ONLD_SUCCESS) ; 


SEE ALSO 
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XXX_Read 


DESCRIPTION 


This function reads data from NAND flash memory. XXX_Read, unlikely XXX_MRead, 
only read sectors within a page boundry. The sector number of the large block and small 
block are different. 


SYNTAX 
INT32 


XXX_Read(UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, UINT8 
*pMBuf, UINT8 *pSBuf, UINT32 nFlag) 


PARAMETERS 

Parameter Type In/Out Description 

nDev UINT32 In Physical Device Number (0 ~ 7) 

nPsn UINT32 In Physical Sector Number 

nNumOfScts UINT32 In Number of sectors 

pMBuf UINT8 * Out Memory buffer for main array of NAND 
flash memory 

pSBuf UINT8 * Out Memory buffer for spare array of NAND 
flash memory 

nFlag UINT32 In Operation options (ECC on/off) 


nFlag_ has the the operation options as follows . 


Flag Value Description 
LLD_FLAG_ECC_ON (1<<1) ECC on (Read Operation with ECC) 
LLD_FLAG_ECC_OFF (0<<1) ECC off (Read Operation without ECC) 


RETURN VALUE 
Return Value Description 
LLD_SUCCESS Read Success 
LLD_READ_ERROR | ECC Data Integrity Fault (1 or 2bit ECC error) This return 
result code value is available only in case of using Hardware ECC. 


LLD_PREV_WRITE_ERROR In DCOP (Deferred Check Operation), previous write 
| LLD_PREV_OP_RESULT _ error happens. 

LLD_PREV_ERASE_ERROR In DCOP (Deferred Check Operation), previous erase 
| LLD_PREV_OP_RESULT _ error happens. 

LLD_ILLEGAL_ACCESS Illegal Read Operation 

LLD_READ_DISTURBANCE __ 1bit ECC error by read disturbance happens. 


REMARKS 
This function is a mandatory flash operation function. 
DCOP (Deferred Check Operation) : a method optimizing the operation performance. The 


DCOP method is a procedure to terminate the function (write or erase) right after the 
command issue. Then it checks the result of the operation at next function call. 
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The parameters nPsn and nNumOfScts read data as a unit of a sector. 
For more information about the byte alignment, refer to 7.5 Byte Alignment Restrictions. 


EXAMPLE 


: #include 
| #include 
| #include 
| #include 


<XSRTypes.h> 
<PAM.h> 
<LLD.h> 
<XXX.h> 


| BOOL32 
| Example (VOID) 
fe 


nErr = stLFT[nVol] 


if 
{ 


(nErr 


return 
} 


return (TRUE32); 


.Read (nDev, 


printf (“XXX_Read () 
(FALSE32) ; 


(1) Example to call the function ; 


/* Header File of Low Level Device Driver KJ 


INT32 nErr; 

UINT32 nDev = 0; 

UINT32 nVol = 0; 

UINT32 nPSN = 0; 

UINT32 nNumOfScts = 1; 

UINT8 aMBuf [LLD_MAIN_SIZE]; 
UINT8 aSBuf [LLD_SPARE_SIZE]; 
UINT32 nFlag = LLD_FLAG _ECC_ON; 
LowFuncTbl stLFT[MAX_VOL]; 

PAM RegLFT((VOID *)sStLFT); 


nPSN, nNumOfScts, 
aSBuf, nFlag); 


aMBuf, 


!= LLD_SUCCESS) 


fail. ErrCode = %x\n”, nErr); 


(2) Example to implement the function in OneNAND ; 


| INT32 


| ONLD_Read(UINT32 nDev, 
i UINT8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag) 


inf 
i INT32 
INT16 
INT32 
INT32 
INT32 
INT16 
INT32 
INT16 
INT16 
INT32 
JINT32 
INT32 


nCnt; 
nBSA; 
*pONLDMBuf; 
*pONLDSBuf; 
nBAddr; 
nPbn; 
nPpn; 
nEccRes 
nEccMask 
nPsnO 
nSctsO 
nRes; 


GaGaqqqaaqaqaaqaa 


fon} 


UINT32 nPsn, UINT32 nScts, 


= (UINT16) 0x0; 
= (UINT16) 0x0; 


= nPsn; 


= nScts; 
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nBAddr = 


if 
{ 


((pMBuf == NULL) && 


return 


} 


nPbn = 
nPpn = 


GET_PBN (nDev, 
GET_PPN (nDev, 


nPsn); 
nPsn); 


/* ECC 
for (nCnt = 0; nCnt < nScts; 


(pMBuf != NULL) 


nEccMask |= (0x08 << 
(pSBuf != NULL) 
nEccMask |= (Ox02 << 


if 
{ 


((nRes = 


pstPrevOpInfo[nDev]->ePreOp 


return nRes; 


} 


ONLD_REG_START_ADDR2 (nBAddr) 


/* Block Number Set */ 
ONLD_REG _START_ADDR1 (nBAddr) 


/* Sector Number Set */ 
ONLD_REG_START_ADDR8 (nBAddr) 
= (UINT16) ( 


((nPsn << astONLDInfo[nDev] .nFPASelSft) 


GET_DEV_BADDR (nDev) ; 


_ChkPrevOpResult (nDev) ) 


(pSBuf == NULL) ) 


(ONLD_ILLEGAL_ ACCESS) ; 


Value Bit Mask Setting */ 
nCnt+t) 


(nCnt * 4)); 


(nCnt * 4)); 


!= ONLD_SUCCESS) 


= NONE; 


(UINT16) MAKE_DBS (nPbn) ; 


(UINT16) MAKE_FBA(nPbn) ; 


& MASK_FPA) 


| (nPsn & astONLDInfo[nDev] .nFSAMask) ); 


nBSA = 


/* Start Buffer Selection */ 


ONLD_REG_START_BUF (nBAddr) 


= (UINT16) ((nBSA & MASK_BSA) 


(UINT16) MAKE _BSA(nPsn, 


GET_NXT_BUF_SEL (nDev) ) ; 


| (nScts & MASK_BSC)); 


if (nFlag & ONLD_FLAG_ECC_ON) 

{ 
/* System Configuration Reg set (ECC On) */ 
ONLD_DBG_PRINT ( (TEXT ("[ONLD MSG] ECC ON\r\n"))); 
ONLD_REG_SYS_CONF1 (nBAddr) &= CONF1_ECC_ON; 

} 

else 


{ 


/* System Configuration Reg set 
ONLD_DBG_PRINT ( (TEXT ("[ONLD 


(ECC Off) */ 


MSG] ECC OFF\r\n"))); 
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ONLD_REG_SYS_CONF1 (nBAddr) = CONF 1_ECC_OFF; 
} 


/* INT Stat Reg Clear */ 


ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 
Fa ea ee a ee ee ee ee ee */ 
/*ONLD Read CMD is issued */ 
Pieroni bem etesaedeennsee die ee eS */ 
if (pMBuf != NULL) 


{ 
/* Page Read Command issue */ 
ONLD_DBG_PRINT((TEXT("[ONLD : MSG] Read Page\r\n"))); 
ONLD_REG_CMD (nBAddr) 

= (UINT16) ONLD_CMD_READ_PAGE; 


} 
else 
{ 
/* Spare Read Command issue */ 
ONLD_DBG_PRINT((TEXT("[ONLD : MSG] Read Spare\r\n"))); 
ONLD_REG_CMD (nBAddr) 
= (UINT16) ONLD_CMD_READ_ SPARE; 


} 


while (GET_ONLD_INT_STAT(nBAddr, PEND_READ) 
!= (UINT16) PEND_READ) 


/* Wait until device ready */ 


} 


pPONLDMBuf = (UINT32%*) GET_ONLD_MBUF_ADDR ( 
nBAddr, nPsnO, GET_NXT_BUF_SEL (nDev) ); 


pONLDSBuf = (UINT32*) GET_ONLD_SBUF_ADDR(nBAddr, 
nPsnO, GET_NXT_BUF_SEL(nDev) ); 
if (pMBuf != NULL) 


{ 


/* Memcopy for main data */ 
_ReadMain (pMBuf, pONLDMBuf, nScts0O); 


} 
if (pSBuf != NULL) 


{ 
/* Memcopy for spare data */ 
_ReadSpare (pSBuf, pONLDSBuf, nScts0O); 


} 

pstPrevOpInfo[nDev] ->nBufSel = GET_NXT_BUF_SEL (nDev) ; 
if (nFlag & ONLD_FLAG_ECC_ON) 

{ 


nEccRes = (ONLD_REG_ECC_STAT(nBAddr) & nEccMask) ; 


if (nEccRes != 0) 
{ 
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return (ONLD_READ ERROR nEccRes) ; 


return (ONLD_SUCCESS) ; 


SEE ALSO 
XXX_Write, XXX_Erase, XXX_Copyback, XXX_MRead, XXX_MWrite, 
XXX_MErase, XXX_EraseVerify 
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XXX_Write 


DESCRIPTION 


This function writes data into NAND flash memory. XXX_Write, unlikely XXX_MWrite, 
only write sectors within a page boundry. The sector number of the large block and small 
block are different. 


SYNTAX 
INT32 


XXX_Write(UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, UINT8 
*pMBuf, UINT8 *pSBuf, UINT32 nFlag) 


PARAMETERS 

Parameter Type In/Out Description 

nDev UINT32 In Physical Device Number (0 ~ 7) 

nPsn UINT32 In Physical Sector Number 

nNumOfScts UINT32 In Number of sectors 

pMBuf UINT8 * In Memory buffer for main array of NAND 
flash memory 

pSBuf UINT8 * In Memory buffer for spare array of NAND 
flash memory 

nFlag UINT32 In Operation options (ECC on/off, Sync/Async) 


nFlag_ has the the operation options as follows . 


Flag Value Description 

LLD_FLAG_ASYNC_OP  (1<<0) Asynchronous Operation 
LLD_FLAG_SYNC_OP ( Synchronous Operation 
LLD_FLAG_ECC_ON (1<<1) ECC on (Read Operation with ECC) 
LLD_FLAG_ECC_OFF ( ECC off (Read Operation without ECC) 


Flag value is devided into Sync/Async Operation flag and ECC on/off flag. These two flags 
can be merged as follow. 


nFlag = LLD_FLAG SYNC_OP | LLD_FLAG_ECC_ON; 


RETURN VALUE 
Return Value Description 
LLD_SUCCESS Write Success 
LLD_WRITE_ERROR Write Failure 
LLD_PREV_WRITE_ERROR | In DCOP (Deferred Check Operation), previous 
LLD_PREV_OP_RESULT write error happens 
LLD_PREV_ERASE_ERROR | In DCOP (Deferred Check Operation), previous 
LLD_PREV_OP_RESULT erase error happens 
LLD_WR_PROTECT_ERROR Write Operation at Locked Area 
LLD_ILLEGAL_ACCESS Illegal Write Operation 

REMARKS 
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This function is a mandatory flash operation function. 


DCOP(Deferred Check Operation) : a method optimizing the operation performance. The 
DCOP method is a procedure to terminate the function (write or erase) right after the 
command issue. Then it checks the result of the operation at next function call. 


The parameters nPsn and nNumOfScts write data as a unit of a sector. 
For more information about the byte alignment, refer to Chapter 7.5 Byte Alignment 
Restrictions. 


In order to support asynchronous mode, codes which execute next steps must be added. 
First, check the value of a flag. And then, clear an interrupt. Finally, enable the interrupt. 
For more information about the interrupt, refer to Chapter 7.2 Interrupt. 


EXAMPLE 


: #include <XSRTypes.h> 

| #include <PAM.h> 

i #include <LLD.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver */ 


(1) Example to call the function ; 


| BOOL32 


_ Example (VOID) 
Lf 
i INT32 nErr; 
UINT32 nDev = 0; 
UINT32 nVol = 0; 
UINT32 nPSN = 0; 
UINT32 nNumOfScts = 4; 
UINT8 aMBuf [LLD_MAIN SIZE * 4]; 
UINT8 aSBuf[LLD_SPARE SIZE * 4]; 
UINT32 nFlag = LLD_FLAG_ASYNC_OP | LLD_FLAG_ ECC_ON; 


LowFuncTbl stLFT[MAX_VOL]; 
PAM RegLFT( (VOID *)stLFT); 


nErr = stLFT[nVol].Write(nDev, nPSN, nNumOfScts, aMBuf, 
aSBuf, nFlag); 


if (nErr != LLD_SUCCESS) 

{ 
printf (“XXX_Write() fail. ErrCode = %x\n”, nErr); 
return (FALSE32); 

} 

return (TRUE32); 


: INT32 

| ONLD_Write (UINT32 nDev, UINT32 nPsn, UINT32 nScts, UINT8 *pMBuf, 
| UINT8 *pSBuf, 

! UINT32 nFlag) 


(2) Example to implement the function in OneNAND 


| UINT16 nBSA; 
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UINT32 *pONLDMBuf, *pONLDSBuf; i 
UINT32 nBAddr; 
UINT32 nPbn; 
INT32 nRes; 


nBAddr = GET_DEV_BADDR (nDev) ; 


if ((pMBuf == NULL) && (pSBuf == NULL) ) 
{ 

return (ONLD_ILLEGAL_ACCESS) ; 
} 


nPbn = GET_PBN(nDev, nPsn); 


if ((GET_DEV_DID(nDev) & 0x0008) == DDP_CHIP) 
{ 
if ((mRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 
{ 
return nRes; 
} 
} 
/* Device BufferRam Select */ 
ONLD_REG_START_ADDR2 (nBAddr) = (UINT16)MAKE DBS (nPbn) ; 


pONLDMBuf (UINT32*) GET_ONLD_MBUF_ADDR ( i 
nBAddr, nPsn, GET_NXT_BUF_SEL(nDev) ); } 
PONLDSBuf = (UINT32*) GET_ONLD_SBUF_ADDR ( i 


nBAddr, nPsn, GET_NXT_BUF_SEL (nDev)); | 


if (pMBuf != NULL) 
{ 
/* Memcopy for main data */ 
_WriteMain(pMBuf, pONLDMBuf, nScts); 
} 


if (pSBuf != NULL) 
{ 
/* Memcopy for spare data */ 
_WriteSpare(pSBuf, pONLDSBuf, nScts); 
} 


else 


{ 
/* Memset for spare data Oxff*/ 
MEMSET (pONLDSBuf, OxFF, (ONLD_SPARE_SIZE * nScts)); 


if ((GET_DEV_DID(nDev) & 0x0008) != DDP_CHIP) 
if ((nRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 
{ 


return nRes; 


} 


/* Block Number Set */ 
ONLD_REG_START_ADDR1 (nBAddr) = (UINT16)MAKE_ FBA(nPbn) ; 
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/* Sector Number Set */ 

ONLD_REG_START_ADDR8 (nBAddr) = (UINT16) ( 
((nPsn << astONLDInfo[nDev].nFPASelSft) & MASK _ FPA) 
| (nPsn & astONLDInfo[nDev] .nFSAMask) ); 


nBSA = (UINT16)MAKE_BSA(nPsn, GET_NXT_BUF_SEL (nDev) ); 


ONLD_REG_START_BUF (nBAddr) = 
(UINT16) ((nBSA & MASK_BSA) | (nScts & MASK_BSC) ); 


if (nFlag & ONLD_FLAG_ECC_ON) 

{ 
/* System Configuration Reg set (ECC On) */ 
ONLD_DBG_PRINT ((TEXT("([ONLD : MSG] ECC ON\r\n"))); 
ONLD_REG_SYS_CONF1(nBAddr) &= CONF1_ECC_ON; 

} 

else 

{ 
/* System Configuration Reg set (ECC Off) */ 
ONLD_DBG_PRINT((TEXT("([ONLD : MSG] ECC OFF\r\n"))); 
ONLD_REG_SYS_CONF1 (nBAddr) = CONF 1_ECC_OFF; 

} 


/* in case of async mode, interrupt should be enabled */ 
if (nFlag & ONLD_FLAG _ASYNC_OP) 
{ 


PAM ClearInt ( (UINT32) XSR_INT_ID_NAND_0); 
PAM _EnableInt ( (UINT32) XSR_INT_ID_NAND_0); 


} 


/* INT Stat Reg Clear */ 


ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 
Ppeeadeeseeeaceaseceaees se een sacedeneseeeseees */ 
/* ONLD Write CMD is issued ava 
Pee ewes See gee = eee eee */ 
if (pMBuf != NULL) 


/* Main Write Command issue */ 


ONLD_DBG_PRINT((TEXT("([ONLD : MSG] Write Page\r\n"))); 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_WRITE_PAGE; 

} 

else 


{ 
/* Spare Write Command issue */ i 
ONLD_DBG_PRINT ((TEXT("[ONLD : MSG] Write Spare\r\n"))); | 


ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_WRITE_SPARE; 
} 
pstPrevOpInfo[nDev] ->ePreOp = WRITE; 
pstPrevOpiInfo[nDev]->nPsn = nPsn; 
pstPrevOpInfo[nDev]->nScts = nScts; 
pstPrevOpInfo[nDev]->nFlag = nFlag; 
pstPrevOpInfo[nDev] ->nBufSel = GET_NXT_BUF_SEL (nDev) ; 


return (ONLD_SUCCESS) ; 
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SEE ALSO 
XXX_Read, XXX_Erase, XXX_Copyback, XXX_MRead, XXX_MWrite, 
XXX_MErase, XXX_EraseVerify 
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XXX_Erase 


DESCRIPTION 
This function erases a block of NAND flash memory. 
SYNTAX 


INT32 
XXX_Erase (UINT32 nDev, UINT32 nPbn, UINT32 nFlag) 


PARAMETERS 
Parameter Type In/Out Description 
nDev UINT32 In Physical Device Number (0 ~ 7) 
nPbn UINT32 In Physical Block Number 
nFlag UINT32 In Operation options (Sync/Async) 


nF lag _ has the the operation options as follows. 


Flag Value Description 

LLD_FLAG_ASYNC_OP  (1<<0) Asynchronous Operation 

LLD_FLAG_SYNC_OP (0 <<0) Synchronous Operation 
RETURN VALUE 

Return Value Description 

LLD_SUCCESS Erase Success 

LLD_ERASE_ERROR Erase Failure 


LLD_WR_PROTECT_ERROR Erase Operation Error at Locked Area 
LLD_PREV_WRITE_ERROR| In DCOP (Deferred Check Operation), previous write 


LLD_PREV_OP_RESULT error happens 
LLD_PREV_ERASE_ERROR| In DCOP (Deferred Check Operation), previous erase 
LLD_PREV_OP_RESULT error happens 
LLD_ILLEGAL_ACCESS Illigal Erase Operation 
REMARKS 


This function is a mandatory flash operation function. 


DCOP(Deferred Check Operation) : a method optimizing the operation performance. The 
DCOP method is a procedure to terminate the function (write or erase) right after the 
command issue. Then it checks the result of the operation at next function call. 


In order to support asynchronous mode, codes which execute next steps must be added. 
First, check the value of a flag. And then, clear an interrupt. Finally, enable the interrupt. 


For more information about the interrupt, refer to Chapter 7.2 Interrupt. 


EXAMPLE 


(1) Example to call the function 
| #include <XSRTypes.h> i 
i #include <PAM.h> 
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_#include <LLD.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver af] 


| BOOL32 
| Example (VOID) 
| { 


INT32 nErr; 

UINT32 nDev = 0; 

UINT32 nVol = 0; 

UINT32 nPbn = 0; 

UINT32 nFlag = LLD_FLAG_ASYNC_OP; 


LowFuncTbl stLFT[MAX_VOL]; 


PAM RegLFT( (VOID *)stLFT); 
nErr = stLFT[nVol].Erase(nDev, nPbn, nFlag) 


if (nErr != LLD_SUCCESS) 

{ 
printf (“XXX_Erase()fail. ErrCode = %x\n"”, nErr); 
return (FALSE32); 

} 

return (TRUE32); 


(2) Example to implement the function in OneNAND 
| INT32 i 


| ONLD_Erase (UINT32 nDev, UINT32 nPbn, UINT32 nFlag) 
| { 
| UINT32 mnBAddr; 
UINT32 nRes; 


nBAddr = GET_DEV_BADDR (nDev) ; 


if ((nRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 
{ 
return nRes; 


} 


/* Block Number Set */ 
ONLD_REG_START_ADDR1 (nBAddr) = (UINT16)MAKE_ FBA(nPbn) ; 
ONLD_REG_START_ADDR2 (nBAddr) (UINT16) MAKE _ DBS (nPbn) ; 


/* INT Stat Reg Clear */ 


ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 

PR al SES ee ee SE ee * / 

/* ONLD Erase CMD is issued */ 

[Fass Sse eee Se a ee ee ee ee es —*/ 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_ERASE_BLK; 
pstPrevOpInfo [nDev] ->ePreOp = ERASE; 


pstPrevOpiInfo[nDev]->nPsn 

= nPbn * GET_SCTS_PER_BLK (nDev) ; 
pstPrevOpiInfo[nDev]->nFlag = nFlag; 
/* in case of async mode, interrupt should be enabled */ 
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if (nFlag & ONLD_FLAG_ASYNC_OP) 
{ 


PAM ClearInt ( (UINT32) XSR_INT_ID_NAND_0); 
PAM EnableInt ( (UINT32) XSR_INT_ID_NAND_0); 


return (ONLD_SUCCESS) ; 


SEE ALSO 
XXX_Read, XXX_Write, XXX_Copyback, XXX_MRead, XXX_MWrite, 
XXX_MErase, XXX_EraseVerify 
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XXX_MRead 


DESCRIPTION 


This function reads data from NAND flash memory. XXX_MRead, unlikely XXX_Read, 
only read multiple sectors within a block boundry. 


When an error occurs, LLD can return ECC error. If 1bit error occurs, this function returns 
SUCCESS. If 2bit error occurs, this function performs the read operation of the remaining 
sector and then returns READ ERROR. 


SYNTAX 
INT32 


XXX_MRead (UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, SGL 
*pstSGL, UINT8 *pSBuf, UINT32 nFlag) 


PARAMETERS 

Parameter Type In/Out Description 

nDev UINT32 In Physical Device Number (0 ~ 7) 

nPsn UINT32 In Physical Sector Number 

nNumOfScts UINT32 In Number of sectors 

pstSGL SGL * Out Scatter gather list structure for main array of 
NAND flash memory 

pSBuf UINTS8 * Out Memory buffer for spare array of NAND 
flash memory 

nFlag UINT32 In Operation options (ECC on/off) 


nFlag_ has the the operation options as follows. 


Flag Value Description 

LLD_FLAG_ECC_ON (1<<1) ECC on (Read Operation with ECC) 

LLD_FLAG_ECC_OFF (0<<1) ECC off (Read Operation without ECC) 
RETURN VALUE 

Return Value Description 

LLD_SUCCESS Read Success 

LLD_READ_ERROR | ECC _ Data Integrity Fault (1 or 2bit ECC error) This return 

result code value is available only in case of using Hardware ECC 

LLD_WRITE_ERROR | In DCOP (Deferred Check Operation), previous write 

LLD_PREV_OP_RESULT error happens. 

LLD_ERASE_ERROR | In DCOP (Deferred Check Operation), previous erase 

LLD_PREV_OP_RESULT error happens. 

LLD_ILLEGAL_ACCESS Illegal Read Operation 


LLD_READ_DISTURBANCE _ 1|bit ECC error by read disturbance happens. 
REMARKS 
This function is a mandatory flash operation function. 


DCOP (Deferred Check Operation) : a method optimizing the operation performance. The 


XSR v1.5.1 Porting Guide 110 


SAMSUNG DMT 


ave bne eb laviled 


DCOP method is a procedure to terminate the function (write or erase) right after the 
command issue. Then it checks the result of the operation at next function call. 


The parameters nPsn and nNumOfScts read data as a unit of a sector. 

For more information about the byte alignment, refer to 7.5 Byte Alignment Restrictions. 
SGL data structure is declared in XsrTypes.h. 

O sGu data structure 


| typedef struct 
if 


UINT8 nElements; 
i SGLEntry stSGLEntry [XSR_MAX_SGL_ENTRIES]; 
|} SGL; 


SGLEntry data structure is declared in XsrTypes.h 
O1SGLEntry data structure 


_ typedef struct 
i{ 
i UINT8* pBuf; /* Buffer for data */ 
UINT16 nSectors; 
/* Number of sectors this entry represents */ 
i UINT8 nFlag; /* user data or meta data ee 
i} SGLEntry; 


SGL is abbreviation for Scatter Gather List. To read whole requested data and store it into 
several buffers within one function call, we use SGL. 


EXAMPLE 


: #include <XSRTypes.h> 

| #include <PAM.h> 

| #include <LLD.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver | 


(1) Example to call the function ; 


| BOOL32 
| Example (VOID) 
lf 


INT32 nErr; 

UINT32 nDev 0; 

UINT32 nVol = 0; 

UINT32 nPSN = 0; 

UINT32 nNumOfScts = 1; 

SGL stSGL; 

UINT8 aMBuf [LLD_MAIN_ SIZE * nNumOfScts]; 
UINT8 aSBuf [LLD_SPARE SIZE * nNumOfScts]; 
UINT32 nFlag = LLD_FLAG_ECC_ON; 


LowFuncTbl stLFT[MAX_VOL]; 


PAM RegLFT((VOID *)stLFT) ; 
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stSGL.stSGLEntry[0].pBuf = aMBuf; 
stSGL.stSGLEntry[0].nSectors = nNumOfScts; 
stSGL.stSGLEntry[0].nFlag = SGL_ENTRY_USER_DATA; 


stSGL.nElements = 1; 


nErr = stLFT[nVol].MRead(nDev, nPSN, nNumOfScts, &stSGL, 
aSBuf, nFlag); 


if (nErr != LLD_SUCCESS) 

{ 
printf ("XXX_Read() fail. ErrCode = %x\n", nErr); 
return (FALSE32); 


} 
return (TRUE32); 


: INT32 

| ONLD_MRead (UINT32 nDev, UINT32 nPsn, UINT32 nScts, SGL *pstSGL, 
| UINT8 *pSBuf, 

i UINT32 nFlag) 


(2) Example to implement the function in OneNAND ; 


UINT32 nCnt; 

UINT16 nBSA; 

UINT32 *pONLDMBuf; 

UINT32 *pONLDSBuf; 

UINT32 nBAddr; 

UINT16 nPbn; 

UINT16 nEccRes = (UINT16) 0x0; 
UINT16 nEccMask = (UINT16) 0x0; 
UINT32 nFlagO = nFlag; 
UINT32 nReadPsn; 

UINT32 nCurReadPsn; 

UINT32 nReadScts = 0; 

UINT32 nCurReadScts; 

UINT32 nRemainScts; 

UINT32 nRet = ONLD_SUCCESS; 
UINT8 nSGLIdx = 0; 

UINT32 nSctCount = 0; 

UINT8 *pMBuf; 


INT32 nRes; 


if (pstSGL == NULL) 
return (ONLD_ILLEGAL_ ACCESS) ; 


nBAddr = GET_DEV_BADDR (nDev) ; 
if ((nRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 
{ 


pstPrevOpInfo[nDev]->ePreOp = NONE; 
return nRes; 


pPMBuf = pstSGL->stSGLEntry [nSGLIdx] .pBuf; 


XSR v1.5.1 Porting Guide 112 


SAMSUNG D0G0T ai 


aver pee a liwviled 


nRemainScts = nScts; 
nReadPsn = nPsn; 
switch (nReadPsn & astONLDInfo[nDev] .nSctSelSft) 
{ 
case 0: 
nReadScts = 
(astONLDInfo[nDev].nSctsPerPG > nRemainScts) ? 
nRemainScts : astONLDInfo[nDev].nSctsPerPG; 
break; 
case l: 
nReadScts = 
(astONLDInfo[nDev] .nSctSelSft > nRemainScts) ? 
nRemainScts : astONLDInfo[nDev] .nSctSelSft; 


break; 
case 2: 
nReadScts = (2 > nRemainScts) ? 
nRemainScts : 2; 
break; 
case 3: 
nReadScts = (1 > nRemainScts) ? 
nRemainScts : 1; 
break; 


nPbn = GET_PBN(nDev, nReadPsn) ; 


/* Block Number Set */ 
ONLD_REG_START_ADDR1 (nBAddr) = (UINT16)MAKE_ FBA(nPbn) ; 
ONLD_REG_START_ADDR2(nBAddr) = (UINT16)MAKE_ DBS (nPbn) ; 


/* Sector Number Set */ 

ONLD_REG_START_ADDR8 (nBAddr) = (UINT16) ( 

((nReadPsn << astONLDInfo[nDev].nFPASelSft) & MASK _FPA) 
| (nReadPsn & astONLDInfo[nDev] .nFSAMask) ); 


nBSA = 
(UINT16)MAKE_BSA(nReadPsn, GET_CUR_BUF_SEL (nDev) ); 


/* Start Buffer Selection */ 
ONLD_REG_ START_BUF (nBAddr) = 
(UINT16) ((nBSA & MASK_BSA) | (nReadScts & MASK_BSC) ); 


if (nFlag & ONLD_FLAG_ECC_ON) 

{ 
/* System Configuration Reg set (ECC On) */ 
ONLD_DBG_PRINT((TEXT("[ONLD : MSG] ECC ON\r\n"))); 
ONLD_REG_SYS_CONF1(nBAddr) &= CONF1_ECC_ON; 

} 

else 

{ 
/* System Configuration Reg set (ECC Off) */ 
ONLD_DBG_PRINT((TEXT("([ONLD : MSG] ECC OFF\r\n"))); 
ONLD_REG_SYS_CONF1 (nBAddr) |= CONF 1_ECC_OFF; 
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/* INT Stat Reg Clear */ 


ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 
fe ec eee nsaeeninnin daa eeeena sete */ 
/* ONLD Read CMD is issued a 
fp oe eee */ 
if (pMBuf != NULL) 


/* Page Read Command issue */ 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_READ_PAGE; 
} 


else 


{ 


/* Spare Read Command issue */ 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_READ_ SPARE; 


if (nFlagO & ONLD_FLAG_ECC_ON) 
{ 
/* ECC Value Bit Mask Setting */ 
for (nCnt = 0; nCnt < nReadScts; nCnt+t+) 


if (pMBuf != NULL) 
nEccMask = (Ox08 << (nCnt * 4)); 
if (pSBuf != NULL) 


nEccMask |= (Ox02 << (nCnt * 4)); 


nCurReadPsn = nReadPsn; 
nCurReadScts = nReadScts; 


nRemainScts -= nReadScts; 

nReadPsn += nReadScts; 

nReadScts = 
(astONLDInfo[nDev].nSctsPerPG > nRemainScts) ? 
nRemainScts : astONLDInfo[nDev] .nSctsPerPG; 


while (GET_ONLD_INT_STAT(nBAddr, PEND_READ) 
!=  (UINT16) PEND_READ) 


/* Wait until device ready */ 
if (nFlagO & ONLD_FLAG_ECC_ON) 
{ 

/* No Cache Read */ 


nEccRes = (ONLD_REG_ECC_STAT(nBAddr) & nEccMask) ; 


i if (nEccRes != 0) i 
{ 
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nRet = ONLD_READ_ERROR nEccRes; 


while (nRemainScts > 0) 


{ 


nPbn = GET_PBN(nDev, nReadPsn) ; 
nSctCount += nCurReadScts; 


if (nSctCount == pstSGL->stSGLEntry [nSGLIdx] .nSectors) 
{ 

nSctCount = 0; 

nSGLIdx++; 


if (pstSGL->stSGLEntry [nSGLIdx] .nFlag 
== SGL_ENTRY_META_ DATA) 


nReadPsn += pstSGL->stSGLEntry [nSGLIdx] .nSectors; 
nReadScts -= pstSGL->stSGLEntry [nSGLIdx] .nSectors; 
nRemainScts —-= pstSGL->stSGLEntry [nSGLIdx] .nSectors; 
nSctCount = 0; 


nSGLIdx++; 
if (GET_SCTS_PER_PG(nDev) == 2) 
{ 
nCurReadPsn = nReadPsn; 
nCurReadScts = nReadScts; 
nReadScts = 


(astONLDInfo[nDev] .nSctsPerPG > nRemainScts) 2] 
nRemainScts : astONLDInfo[nDev] .nSctsPerPG; i 
continue; 


} 


/* Block Number Set */ 
ONLD_REG START_ADDR1 (nBAddr) 
ONLD_REG_START_ADDR2 (nBAddr) 


(UINT16) MAKE_FBA(nPbn) ; 
(UINT16) MAKE_DBS (nPbn) ; 


ll 


/* Sector Number Set */ 
ONLD_REG_START_ADDR8 (nBAddr) (UINT16) ( 
((nReadPsn << astONLDInfo[nDev] .nFPASelSft) & MASK_FPA) 
| (nReadPsn & astONLDInfo[nDev] .nFSAMask) ); 


nBSA = 
(UINT16)MAKE_BSA(nReadPsn, GET_NXT_BUF_SEL (nDev) ); 


/* Start Buffer Selection */ 
ONLD_REG_ START_BUF (nBAddr) = 
(UINT16) ((nBSA & MASK_BSA) | (nReadScts & MASK_BSC) ); 


/* INT Stat Reg Clear */ 
ONLD_REG_INT(nBAddr) = (UINT16) INT_CLEAR; 


XSR v1.5.1 Porting Guide 115 


SAMSUNG DMG0T ai 


| 
aver pee a liviled 


ONLD Read CMD is issued 


(pMBuf != NULL) 


ONLD_REG_CMD (nBAddr) = (UINT16)ONLD_CMD_READ_ PAGE; 
} 
else 
{ 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_READ_ SPARE; 
PONLDMBuf = (UINT32*) GET_ONLD_MBUF_ADDR ( 
nBAddr, nCurReadPsn, GET _CUR_BUF_SEL(nDev) ); 
PONLDSBuf = (UINT32*) GET_ONLD_SBUF_ADDR ( 
nBAddr, nCurReadPsn, GET _CUR_BUF_SEL(nDev) ); 


if 
{ 


(pMBuf != NULL) 

/* Memcopy for main data */ 
_ReadMain(pMBuf, pONLDMBuf, nCurReadScts) ; 
pPMBuf += (ONLD_MAIN_SIZE * nCurReadScts) ; 


if 
{ 


(pSBuf != NULL) 

/* Memcopy for main data */ 
_ReadSpare(pSBuf, pONLDSBuf, nCurReadScts) ; 
pSBuf += (ONLD_SPARE_SIZE * nCurReadScts) ; 


LE 
{ 


(nFlagO & ONLD_FLAG_ECC_ON) 


/* ECC Value Bit Mask Setting */ 


for (nCnt = 0; nCnt < nReadScts; nCnt+t+) 
if (pMBuf != NULL) 
nEccMask |= (0x08 << (nCnt * 4)); 
io (pSBuf != NULL) 
nEccMask |= (0x02 << (nCnt * 4)); 


pstPrevOpInfo[nDev]->nBufSel = GET_NXT_BUF_SEL (nDev) ; 


nCurReadPsn = nReadPsn; 

nCurReadScts = nReadScts; 
nRemainScts -= nReadScts; 
nReadPsn += nReadScts; 
nReadScts = 


(astONLDInfo[nDev].nSctsPerPG > nRemainScts) ? 
nRemainScts astONLDInfo[nDev] .nSctsPerPG; 
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while (GET_ONLD_INT_STAT(nBAddr, PEND_READ) 
!=  (UINT16) PEND_READ) 


/* Wait until device ready */ 


if (nFlagO & ONLD_FLAG_ECC_ON) 
{ 
/* No Cache Read */ 
nEccRes = (ONLD_REG_ECC_STAT(nBAddr) & nEccMask) ; 


if (nEccRes != 0) 
{ 
nRet = ONLD_READ_ERROR nEccRes; 


PONLDMBuf = (UINT32*) GET_ONLD_MBUF_ADDR ( 

nBAddr, nCurReadPsn, GET_CUR_BUF_SEL (nDev) ); 
PONLDSBuf = (UINT32*) GET_ONLD_SBUF_ADDR ( 

nBAddr, nCurReadPsn, GET_CUR_BUF_SEL (nDev) ); 


if (pMBuf != NULL) 

{ 
/* Memcopy for main data */ 
_ReadMain(pMBuf, pONLDMBuf, nCurReadScts) ; 
pPMBuf += (ONLD_MAIN_SIZE * nCurReadScts) ; 


if (pSBuf != NULL) 

{ 
/* Memcopy for spare data */ 
_ReadSpare (pSBuf, pONLDSBuf, nCurReadScts) ; 
pSBuf += (ONLD_SPARE_SIZE * nCurReadScts) ; 


pstPrevOpInfo [nDev]-—>nBufSel = 
GET_NXT_BUF_SEL (nDev) ; 


return (nRet); 


SEE ALSO 
XXX_Read, XXX_Write, XXX_Erase, XXX_Copyback, XXX_MWrite, 
XXX_MErase, XXX_EraseVerify 
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XXX_MWrite 


DESCRIPTION 


This function writes data into NAND flash memory. XXX_MWrite, unlikely XXX_Write, 
only write sectors within a block boundry. 


SYNTAX 


INT32 
XXX_MWrite (UINT32 nD 


PARAMETERS 

Parameter Type 
nDev UINT32 
nPsn UINT32 
nNumOfScts UINT32 
pstSGL SGL * 
pSBuft UINT8 
nFlag UINT32 
pErrPsn UINT32 


ev, UINT32 nPsn, UINT32 nNumOfScts, 
SGL *pstSGL, UINT8 *pSBuf, UINT32 nFlag, UINT32 *pErrPsn) 


In/Out 
In 
In 
In 
In 


* In 


In 


* Out 


Description 

Physical Device Number (0 ~ 7) 

Physical Sector Number 

Number of sectors 

Scatter gather list structure for main array of 
NAND flash memory 

Memory buffer for spare array of NAND 
flash memory 

Operation options (ECC on/off, Sync/Async) 


Pointer of the sector number where the error 
occurs. 

When an error occurs, this function stops the 
write operation. The errored physical sector 
number is put on this parameter. 


nFlag_ has the the operation options as follows . 


Flag 
LLD_FLAG_ASYNC_OP 
LLD_FLAG_SYNC_OP 
LLD_FLAG_ECC_ON 
LLD_FLAG_ECC_OFF 


Value 
(1<<0 
(0<<0 
(1<<1 
( 


) 
) 
) 
0<<1) 


Description 

Asynchronous Operation 

Synchronous Operation 

ECC on (Read Operation with ECC) 
ECC off (Read Operation without ECC) 


Flag value is devided into Sync/Async Operation flag and ECC on/off flag. These two flags 


can be merged as follow. 


nFlag = LLD_FLAG SYNC_OP | LLD_FLAG_ECC_ON; 


RETURN VALUE 


Return Value 
LLD_SUCCESS 
LLD_WRITE_ERROR 
LLD_WRITE_ERROR | 
LLD_PREV_OP_RESULT 
LLD_ERASE_ERROR | 
LLD_PREV_OP_RESULT 


Description 

Write Success 

Write Failure 

In DCOP (Deferred Check Operation), previous 
write error happens 

In DCOP (Deferred Check Operation), previous 
erase error happens 
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LLD_WR_PROTECT_ERROR Write Operation at Locked Area 
LLD_ILLEGAL_ACCESS Illegal Write Operation 
REMARKS 


This function is a mandatory flash operation function. 
DCOP(Deferred Check Operation) : a method optimizing the operation performance. The 
DCOP method is a procedure to terminate the function (write or erase) right after the 


command issue. Then it checks the result of the operation at next function call. 


The parameters nPsn and nNumOfScts write data as a unit of a sector. 
For more information about the byte alignment, refer to 7.5 Byte Alignment Restrictions. 


SGL data structure is declared in XsrTypes.h. 
OSG. data structure 


| typedef struct 
if 


UINT8 nElements; 
i SGLEntry stSGLEntry [XSR_MAX_SGL_ENTRIES]; 
i} SGL; 


SGLEntry data structure is also declared in XsrTypes.h. 
O)SGLEntry data structure 


_ typedef struct 
i{ 
i UINT8* pBuf; /* Buffer for data */ 
UINT16 nSectors; 
/* Number of sectors this entry represents a | 
i UINT8 nFlag; /* user data or meta data * / 
i} SGLEntry; 


SGL is abbreviation for Scatter Gather List. To write whole requested data which exists in 
several different buffers within one function call, we use SGL. 


This function does not support asynchronous mode, whereas XXX_Write supports 
asynchronous mode. 


EXAMPLE 


: #include <XSRTypes.h> 

| #include <PAM.h> 

| #include <LLD.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver ur a | 


(1) Example to call the function ; 


| BOOL32 

| Example (VOID) 

if 

| INT32 nEryr; 
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UINT32 nDev = 0; 

UINT32 nVol = 0; 

UINT32 nPSN = 0; 

SGL stSGL; 

UINT8 aMBuf [LLD_MAIN_ SIZE * nNumOfScts]; 

UINT8 aSBuf [LLD_SPARE SIZE * nNumOfScts]; 

UINT32 nFlag = LLD_FLAG_ECC_ON LLD_FLAG _ SYNC_OP; 


LowFuncTbl stLFT[MAX_VOL]; 
PAM _RegLFT( (VOID *)stLFT); 
stSGL.stSGLEntry[0].pBuf = aMBuf; 


stSGL.stSGLEntry[0].nSectors = nNumOfScts; 
stSGL.stSGLEntry[0].nFlag = SGL_ENTRY_USER_DATA; 


stSGL.nElements = 1; 


nErr = stLFT[nVol] .MWrite(nDev, nPSN, nNumOfScts, &stSGL, 
aSBuf, nFlag); 


if (nErr != LLD_SUCCESS) 

{ 
printf ("XXX_Write() fail. ErrCode = %x\n", nErr); 
return (FALSE32); 

} 

return (TRUE32); 


(2) Example to implement the function in OneNAND ; 
| INT32 i 


| ONLD_MWrite (UINT32 nDev, UINT32 nPsn, UINT32 nScts, SGL *pstSGL, 
| UINT8 *pSBuf, UINT32 nFlag, UINT32 *pErrPsn) 
Lf 


UINT16 nBSA; 

UINT32 *pONLDMBuf; 
UINT32 *pONLDSBuf; 
UINT32 nBAddr; 

UINT32 nPbn; 

UINT32 nWritePsn; 
UINT32 nWriteScts = 0; 
UINT32 nTmpWriteScts; 
UINT8 nBiWriteScts; 
UINT8 nSnapWriteScts; 
UINT32 nRemainScts; 
INT32 nRes; 


INTS8 nSGLIdx; 
INT8 nSGLCount; 
INT32 nSctCount = 0; 


GaGa 


INT8 *pMBuf; 

INT8 *pSGLBuf = NULL; 
INT8 nidx; 

INT8 nPreSGLIdx = 0; 
JINT8 nTmpRemainScts = 0; 
SGLEntry *pSGLEnt; 


Gaaqaa 


fan} 
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if (pstSGL == NULL) 
return (ONLD_ILLEGAL ACCESS) ; 


nBAddr = GET_DEV_BADDR (nDev) ; 


if ((GET_DEV_DID(nDev) & 0x0008) == DDP_CHIP) 
{ 
if ((nRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 
{ 
return nRes; 
} 
} 


/* Previous Operation should be flushed at a upper layer */ 


if (nFlag & ONLD_FLAG_ECC_ON) 
{ 
/* System Configuration Reg set (ECC On) */ 
ONLD_REG_SYS_CONF1(nBAddr) &= CONF1_ECC_ON; 
} 
else 
{ 
/* System Configuration Reg set (ECC Off) */ 
ONLD_REG_SYS_CONF1 (nBAddr) [= CONF 1_ECC_OFF; 
} 


/* Set user Data Buffer point */ 
for (nSGLIdx = 0; nSGLIdx < pstSGL->nElements; nSGLIdx++) 
{ 
if (pstSGL->stSGLEntry[nSGLIdx].nFlag == 
SGL_ENTRY_USER_DATA) 


PMBuf = pstSGL->stSGLEntry [nSGLIdx] .pBuf; 


break; 
} 
} 
nSGLIdx = 0; 
nRemainScts = nScts; 
nWritePsn = nPsn; 


switch (nWritePsn & astONLDInfo[nDev] .nSctSelSft) 
{ 
case 0: 
nWriteScts = 
(astONLDInfo[nDev].nSctsPerPG > nRemainScts) ? 
nRemainScts : astONLDInfo[nDev].nSctsPerPG; 
break; 
case l: 
nWriteScts = 
(astONLDInfo[nDev] .nSctSelSft > nRemainScts) ? 
nRemainScts : astONLDInfo[nDev] .nSctSelSft; 
break; 
case 2: 
nWriteScts = (2 > nRemainScts) ? nRemainScts : 2; 
break; 
case 3: 
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nWriteScts = (1 > nRemainScts) ? nRemainScts : 1; 
break; 


while (nRemainScts > 0) 
{ 
nPbn = GET_PBN(nDev, nWritePsn); 


nTmpWriteScts = nWriteScts; 
nSGLCount = 0; 


if (nSctCount != 0 && i 
pstSGL->stSGLEntry [nSGLIdx].nSectors - nSctCount < | 
nTmpWriteScts) | 


nTmpRemainScts = i 
pstSGL->stSGLEnt ry [nSGLIdx] .nSectors-—nSctCount; } 


do 


nSctCount += 1; 
if (nSctCount >= 
pstSGL->stSGLEntry [nSGLIdx] .nSectors) 


nSctCount = 0; 
nSGLIdx++; 
nSGLCountt++; 
} 
else if (nWriteScts == 1) 
{ 
nSGLCount++; 


} 
} while (--nWriteScts); 


nBiWriteScts = 0; 


nSnapWriteScts 0; 
ONLD_REG_START_ADDR2 (nBAddr) = (UINT16)MAKE_DBS (nPbn) ; 
PONLDMBuf = (UINT32*) GET_ONLD_MBUF_ADDR ( 


nBAddr, nWritePsn, GET_NXT_BUF_SEL(nDev) ); 
PpONLDSBuf = (UINT32*) GET_ONLD_SBUF_ADDR ( i 
nBAddr, nWritePsn, GET_NXT_BUF_SEL(nDev) ); | 


for (nIdx = 0; nIdx < nSGLCount; nIdx+t+) 
{ 
pSGLEnt = pstSGL->stSGLEntry[nPreSGLIdx + nIdx]; 


switch (pSGLEnt-—>nFlag) 
{ 
case SGL_ENTRY_BISCT_VALID_DATA: 


pSGLBuf = pSGLEnt-—>pBuf; 
nBiWriteScts += pSGLEnt-—>nSectors; 
nWriteScts = pSGLEnt-—>nSectors; 
break; 
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case SGL_ENTRY_BISCT_INVALID_DATA: 


pSGLBuf = pSGLEnt-—>pBuf; 
nBiWriteScts += pSGLEnt-—>nSectors; 
nWriteScts = psSGLEnt-—>nSectors; 
break; 
case SGL_ENTRY_META_DATA: 
pSGLBuf = pSGLEnt-—>pBuf; 
nSnapWriteScts += pSGLEnt-—>nSectors; 
nWriteScts = pSGLEnt-—>nSectors; 
break; 
case SGL_ENTRY_USER_DATA: 
if (nTmpRemainScts != 0) 
{ 
nWriteScts = nTmpRemainScts; 
nTmpRemainScts = 0; 
} 
else 
{ 
nWriteScts a 


nTmpWriteScts - nBiWriteScts —nSnapWriteScts; | 
if (nWriteScts > pSGLEnt—>nSectors) i 
{ 

nWriteScts = pSGLEnt-—>nSectors; 


} 
break; 
default: 
return (ONLD_ILLEGAL ACCESS) ; 
} 
if (pSGLEnt->nFlag != SGL_ENTRY_USER_DATA 
&& pSGLBuf != NULL) 


_WriteMain(pSGLBuf, pONLDMBuf, nWriteScts); 
PONLDMBuf += (BUFF_MAIN_SIZE * nWriteScts); 

} 

else if (pMBuf != NULL) 

{ 
/* Memcopy for main data */ 
_WriteMain(pMBuf, pONLDMBuf, nWriteScts); 
pMBuft += (ONLD_MAIN_ SIZE * nWriteScts); 
PONLDMBuf += (BUFF_MAIN_SIZE * nWriteScts); 


nPreSGLIdx = nSGLIdx; 
nWriteScts = nTmpWriteScts; 


if (pSBuf != NULL) 

{ 
/* Memcopy for spare data */ 
_WriteSpare(pSBuf, pONLDSBuf, nWriteScts); 
pSBuf += (ONLD_SPARE_ SIZE * nWriteScts); 

} 

else 


{ 
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/* Memset for spare data Oxff*/ 
MEMSET (pONLDSBuf, OxFF, 
(ONLD_SPARE_SIZE * nWriteScts)); 


if ((nRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 


*pErrPsn = pstPrevOpiInfo[nDev]-—->nPsn; 
return nRes; 


} 


/* Block Number Set */ 
ONLD_REG_ START_ADDR1 (nBAddr) 


ll 


(UINT16) MAKE_FBA(nPbn) ; 


/* Sector Number Set */ 
ONLD_REG_START_ADDR8 (nBAddr) = 
(UINT16) (((nWritePsn << astONLDInfo[nDev] .nFPASelSft) 
& MASK_FPA) 
| (nWritePsn & astONLDInfo[nDev] .nFSAMask) ); 


nBSA = 
(UINT16)MAKE_BSA(nWritePsn, GET_NXT_BUF_SEL (nDev) ); 


ONLD_REG_START_BUF(nBAddr) = i 
(UINT16) ((nBSA & MASK_BSA) | (nWriteScts & MASK_BSC)); | 


/* INT Stat Reg Clear */ 


ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 
[Ree ee Eee Se ee ee * / 
/* ONLD Write CMD is issued af 
f $a ee ee ee eS ee * / 
if (pMBuf != NULL || pSGLBuf != NULL) 
{ 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_WRITE_PAGE; 
} 
else 
{ 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_WRITE_SPARE; | 
} 
pstPrevOpInfo[nDev]->ePreOp = WRITE; 
pstPrevOpiInfo[nDev]->nPsn = nWritePsn; 
pstPrevOpiInfo[nDev]->nScts = nWriteScts; 
pstPrevOpInfo[nDev]->nFlag = nFlag; 
nRemainScts -= nWriteScts; 
nWritePsn += nWriteScts; 
nWriteScts = 


(astONLDInfo[nDev].nSctsPerPG > nRemainScts) ? 
nRemainScts : astONLDInfo[nDev] .nSctsPerPG; 


pstPrevOpInfo [nDev]->nBufSel = 
GET_NXT_BUF_SEL (nDev) ; 
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return (ONLD_SUCCESS) ; 


SEE ALSO 
XXX_Read, XXX_Write, XXX_Erase, XXX_Copyback, XXX_MRead, 
XXX_MErase, XXX_EraseVerify 
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XXX_MErase 


DESCRIPTION 
This function erases blocks of NAND flash memory. XXX_MErase, unlikely XXX_Erase, 
erases multiple blocks simultaneously. When a device supports multi-block erase operation, 
XXX_MErase can be used. 

SYNTAX 


INT32 
XXX_MErase(UINT32 nDev, LLDMEArg *pstMEArg, UINT32 nFlag) 


PARAMETERS 
Parameter Type In/Out Description 
nDev UINT32 In Physical Device Number (0 ~ 7) 
pstMEArg LLDMEArg In Pointer to LLDMEAreg data structure 
nFlag UINT32 In Operation options (Sync/Async) 


nFlag has the the operation options as follows . 


Flag Value Description 
LLD_FLAG_ASYNC_OP  (1<<0)_ Asynchronous Operation 
LLD_FLAG_SYNC_OP (0 <<0) Synchronous Operation 

RETURN VALUE 
Return Value Description 
LLD_SUCCESS Erase Success 
LLD_WR_PROTECT_ERROR| In DCOP (Deferred Check Operation), previous write 
LLD_PREV_OP_RESULT Protection error happens 
LLD_PREV_WRITE_ERROR| In DCOP (Deferred Check Operation), previous write 
LLD_PREV_OP_RESULT error happens 
LLD_PREV_ERASE_ERROR| In DCOP (Deferred Check Operation), previous erase 
LLD_PREV_OP_RESULT error happens 
LLD_ILLEGAL_ACCESS Illigal Erase Operation 

REMARKS 


This function is a mandatory flash operation function. 


DCOP(Deferred Check Operation) : a method optimizing the operation performance. The 
DCOP method is a procedure to terminate the function (write or erase) right after the 
command issue. Then it checks the result of the operation at next function call. 


In order to support asynchronous mode, codes which execute next steps must be added. 
First, check the value of a flag. And then, clear an interrupt. Finally, enable the interrupt. 
For more information about the interrupt, refer to Chapter 7.2 Interrupt. 


XXX_MErase can be used by only devices which support multi-block erase feature (for 
example OneNAND256). Multi-block erase operation erases multiple blocks 


simultaneously. The unit of erase operation is 16 blocks at maximum. After XXX_MErase, 
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the blocks must be verified by XXX_EraseVerify. 


XXX_MErase must have information about blocks to be erased. LLDMEArg data structure 
and LLDMEList data structure that are required for additional information are as follows 


LLDMEArg data structure is declared in LLD.h. 


O LLDMEArg data structure 


| typedef struct { H 
/ LLDMEList *pstMEList; /* Pointer to LLDMEList as a | 


UINT16 nNumOfMList; /* Number of Entries of LLDMEList */ 
UINT16 nBitMapErr; /* Error Bitmap Position of MEList */ i 
BOOL32 bFlag; /* Valid Flag ef | 


|} LLDMEArg; 


Table 5-3 describes LLDMEArg data structure. 


Table 5-3. LLDMEArg data structure in LLD.h 


Member Varilable Description 

pstMEList Pointer to LLDME List data structure 

nNumOfMList Number of blocks to be erased simultaneously. The maximum 
number of blocks is 16. 

nBitMapErr Each bit indicates whether error occurs or not for each block 

bFlag Valid flag for a block list in LLDMEList 


LLDMEList data structure is also declared in LLD.h. 

O LLDMEList data structure 

| typedef struct { : 
i UINT16 nMEListSbn; /* MEList Semi-physical Block Number */ | 


| -UINT16 nMEListPbn; /* MEList Physical Block Number */ | 
i} LLDMEList; i 


Table 5-4 describes LLDMEList data structure. 


Table 5-4. LLDME List data structure in LLD.h 


Member Varilable Description 

nMEListSbn Semi-physical block number of a block in block list 

nMEListPbn Physical block number of a block in block list 
EXAMPLE 


(1) Example to call the function 
| #include <XSRTypes.h> i 
: #include <PAM.h> 
| #include <LLD.h> 


i #include <XXX.h> /* Header File of Low Level Device Driver */ i 
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| BOOL32 
| Example (VOID) 
if 


INT32 nErr; 

UINT32 nDev = 0; 

UINT32 nVol = 0; 

UINT16 nPbn = 13; 

UINT16 nSbn = 13; 

UINT16 nNum = 0; 

UINT16 nNumOfPbn = 1; 

UINT32 nFlag = LLD_FLAG_ASYNC_OP; 
LowFuncTbl stLFT[MAX_VOL]; 

LLDMEArg *pstLLDMEArg [XSR_MAX_DEV]; 
LLDMEList *pstLLDMEList; 


pstLLDMEArg[nDev]->nBitMapErr = (UINT16) 0x0; 
pstLLDMEArg [nDev]—->nNumOfMList = nNumOfPbn; 
pstLLDMEArg [nDev]—->bFlag = TRUE32; 


pStLLDMEList = pstLLDMEArg [nDev]->pstMEList; 


pstLLDMEList [nNum] .nMEListSbn nSbn; 
pstLLDMEList [nNum] .nMEListPbn = nPbn; 


PAM _RegLFT((VOID *) sStLFT); 
nErr = stLFT[nVol].MErase(nDev, pstLLDMEArg[nDev], nFlag) 


if (nErr != LLD_SUCCESS) 

{ 
printf (“XXX_MErase()fail. ErrCode = %x\n”, nErr); 
return (FALSE32); 

} 

return (TRUE32); 


| INT32 
| ONLD_MErase (UINT32 nDev, LLDMEArg *pstMEArg, UINT32 nFlag) 
if 


(2) Example to implement the function in OneNAND ; 


UINT32 nBAddr, nPbn; 

UINT32 nCurPbn; 

UINT32 nFirstchipPbn = Oxffff; 
UINT32 nSecondchipPbn = Oxffff; 
UINT16 nCnt; 

INT32 nRes; 

INT32 nRet = ONLD_SUCCESS; 


LLDMEList *pstMEPList; 
nBAddr = GET_DEV_BADDR (nDev) ; 


if ((nRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 
return nRes; 


pstMEPList = pstMEArg->pstMEList; 
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for(nCnt = 0; nCnt < pstMEArg->nNumOfMList; nCnt+t+) 


{ 


} 


nCurPbn = pstMEPList [nCnt] .nMEListPbn; 


if ((((nCurPbn << 5) & MASK DBS) == 0x0000) 
&& (nFirstchipPbn == Oxffff) ) 


nFirstchipPbn = nCurPbn; 
continue; 
} 
else if ((((nCurPbn << 5) & MASK DBS) == 0x8000) 
&& (nSecondchipPbn == Oxffff) ) 


nSecondchipPbn = nCurPbn; 
continue; 


} 


/* Block Number Set */ i 
ONLD_REG_START_ADDR1 (nBAddr) = (UINT16)MAKE_FBA(nCurPbn); | 
ONLD_REG_START_ADDR2 (nBAddr) =(UINT16)MAKE_DBS(nCurPbn); | 
if (ONLD_REG_WR_PROTECT_STAT(nBAddr) != 
(UINT16) (UNLOCKED_STAT) ) 
{ 
return (ONLD_WR_PROTECT_ERROR) ; 


} 
/* INT Stat Reg Clear */ 


ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 
Fe I Ria ee oye A eno ON NONE ER nO */ 
/* ONLD Erase CMD is issued a 
Se ne Se nee ere nee ees eee ra */ 
ONLD_REG_CMD (nBAddr) = (UINT16)ONLD_CMD_ERASE_MBLK; 


while (GET_ONLD_INT_STAT(nBAddr, PEND_INT) != 
(UINT16) PEND_INT) 


/* Wait until device ready */ 


if ((nFirstchipPbn != Oxffff) && (nSecondchipPbn != Oxffff) ) 


{ 


/* Block Number Set */ 
ONLD_REG_START_ADDR1 (nBAddr) = 

(UINT16) MAKE _FBA(nFirstchipPbn) ; 
ONLD_REG START _ADDR2 (nBAddr) = 

(UINT16) MAKE_DBS (nFirstchipPbn) ; 


if (ONLD_REG_WR_PROTECT_STAT(nBAddr) != 
(UINT16) (UNLOCKED_STAT) ) 
{ 
return (ONLD_WR_PROTECT_ERROR) ; 
} 
/* INT Stat Reg Clear */ 
ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 
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ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_ERASE_BLK; 


while (GET_ONLD_INT_STAT(nBAddr, PEND_ERASE) != 
(UINT16) PEND_ERASE) 
{ 
/* Wait until device ready */ 


} 


/* Block Number Set */ 

ONLD_REG_START_ADDR1 (nBAddr) = 
(UINT16) MAKE_FBA(nSecondchipPbn) ; 

ONLD_REG_START_ADDR2 (nBAddr) = 
(UINT16) MAKE_DBS (nSecondchipPbn) ; 


if (ONLD_REG_WR_PROTECT_STAT(nBAddr) != 
(UINT16) (UNLOCKED_STAT) ) 

{ 
return (ONLD_WR_PROTECT_ERROR) ; 

} 


/* INT Stat Reg Clear */ 
ONLD_REG_INT(nBAddr) = (UINT16) INT_CLEAR; 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_ERASE_ BLK; 


nPbn = nSecondchipPbn; 


} 
else if (nFirstchipPbn != Oxffff) 
{ 
/* Block Number Set */ 
ONLD_REG_START_ADDR1 (nBAddr) = 
(UINT16) MAKE _FBA(nFirstchipPbn) ; 
ONLD_REG_ START_ADDR2 (nBAddr) = 
(UINT16) MAKE _ DBS (nFirstchipPbn) ; 


if (ONLD_REG_WR_PROTECT_STAT(nBAddr) != 
(UINT16) (UNLOCKED_STAT) ) 
{ 
return (ONLD_WR_PROTECT_ERROR) ; 
} 
/* INT Stat Reg Clear */ 
ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 
ONLD_REG_CMD (nBAddr) (UINT16) ONLD_CMD_ERASE_BLK; 


nPbn = nFirstchipPbn; 
} 
else 
{ 
/* Block Number Set */ 
ONLD_REG_START_ADDR1 (nBAddr) = 
(UINT16) MAKE_FBA(nSecondchipPbn) ; 
ONLD_REG_ START _ADDR2 (nBAddr) = 
(UINT16) MAKE_DBS (nSecondchipPbn) ; 
if (ONLD_REG_WR_PROTECT_STAT(nBAddr) != 
(UINT16) (UNLOCKED_STAT) ) 
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return (ONLD_WR_PROTECT_ERROR) ; 
} 
/* INT Stat Reg Clear */ 
ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_ERASE_ BLK; 


nPbn = nSecondchipPbn; 


while (GET_ONLD_INT_STAT(nBAddr, PEND_ERASE) 
!'= (UINT16) PEND_ERASE) 


/* Wait until device ready */ 


pstPrevOpInfo[nDev]—->ePreOp = MERASE; 
pstPrevOpInfo[nDev]->nFlag = nFlag; 
pstPrevOpiInfo[nDev]->nPsn = nPbn * GET_SCTS_PER_BLK (nDev) ; 
MEMCPY (pstPrevOpInfo[nDev]->pstPreMEArg, 

pstMEArg, sizeof (LLDMEArg) ); 


/* in case of async mode, interrupt should be enabled */ 
if (nFlag & ONLD_FLAG_ASYNC_OP) 
{ 


PAM _ClearInt ( (UINT32) XSR_INT_ID_NAND_0); 
PAM _EnableInt ( (UINT32) XSR_INT_ID_NAND_0O); 


return nRet; 


SEE ALSO 
XXX_Read, XXX_Write, XXX_Erase, XXX_Copyback, XXX_MRead, 


XXX_MWrite, XXX_EraseVerify 
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XXX_EraseVerify 


DESCRIPTION 


This function verifies an erase operation whether it checks blocks are properly erased. 
Mainly this function is used with XXX_MErase function. 


SYNTAX 


INT32 
MyLLD_EraseVerify (UINT32 nDev, LLDMEArg *pstMEArg, UINT32 nFlag) 


PARAMETERS 
Parameter Type In/Out _ Description 
nDev UINT32 In Physical Device Number (0 ~ 7) 
pstMEArg LLDMEArg In Pointer to LLDMEArg data structure 
nFlag UINT32 In Operation options (Sync/Async) 


nFlag_ has the the operation options as follows. 


Flag Value Description 
LLD_FLAG_ASYNC_OP  (1<<0) Asynchronous Operation 
LLD_FLAG_SYNC_OP (0 <<0) Synchronous Operation 

RETURN VALUE 
Return Value Description 
LLD_SUCCESS Erase Success 
LLD_WR_PROTECT_ERROR| In DCOP (Deferred Check Operation), previous write 
LLD_PREV_OP_RESULT Protection error happens 
LLD_PREV_WRITE_ERROR| In DCOP (Deferred Check Operation), previous write 
LLD_PREV_OP_RESULT error happens 
LLD_PREV_ERASE_ERROR| In DCOP (Deferred Check Operation), previous erase 
LLD_PREV_OP_RESULT error happens 
LLD_ERASE_ERROR Erase Failure 

REMARKS 


This function is a mandatory flash operation function. 


DCOP(Deferred Check Operation) : a method optimizing the operation performance. The 
DCOP method is a procedure to terminate the function (write or erase) right after the 
command issue. Then it checks the result of the operation at next function call. 


After erase operation, XXX_EraseVerify checks all blocks in LLDMEList of 
LLDMEArg. If blocks that is not erased properly are detected, XXX_EraseVerify 
returns erase error. XXX_MErase requires XXX_EraseVerify becasuse XXX_MErase 
does not support the functionality to verify erase errors. XXX_EraseVerify only can be 
used when a device supports erase verify functionality. For more information about 
LLDMEList and LLDMEArg data structure, refer to the API page of XXX_MErase. 
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EXAMPLE 


; #include <XSRTypes.h> 

| #include <PAM.h> 

| #include <LLD.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver */ | 


(1) Example to call the function ; 


| BOOL32 
| Example (VOID) 
if 


INT32 nErr; 

UINT32 nDev = 0; 

UINT32 nVol = 0; 

UINT16 nPbn = 13; 

UINT16 nSbn = 13; 

UINT16 nNum = 0; 

UINT16 nNumOfPbn = 1; 

UINT32 nFlag = LLD_FLAG_ASYNC_OP; 


LowFuncTbl stLFT[MAX_VOL]; 
LLDMEArg *pstLLDMEArg [XSR_MAX_DEV]; 
LLDMEList *pstLLDMEList; 


pstLLDMEArg[nDev]—->nBitMapErr = (UINT16) 0x0; 
pstLLDMEArg [nDev]—->nNumOfMList = nNumOfPbn; 
pstLLDMEArg [nDev] ->bFlag = TRUE32; 


pstLLDMEList = pstLLDMEArg [nDev]->pstMEList; 


pstLLDMEList [nNum] .nMEListSbn = nSbn; 
pstLLDMEList [nNum] .nMEListPbn nPbn; 


PAM RegLFT((VOID *)stLFT) ; 


nErr = stLFT[nDev] .EraseVerify(nDev, pstLLDMEArg[nDev], 
nFlag) 


if (nErr != LLD_SUCCESS) 

{ 
printf (“XXX_EraseVerify()fail. ErrCode = %x\n"”, nErr); 
return (FALSE32); 


} 
return (TRUE32); 


(2) Example to implement the function in OneNAND 

| INT32 i 
| ONLD_EraseVerify (UINT32 nDev, LLDMEArg *pstMEArg, UINT32 nFlag) 
13 


UINT32 nBAddr; 
UINT32 nCnt; 
INT32 nRet = ONLD_SUCCESS; 


LLDMEList *pstMEPList; 


nBAddr = GET_DEV_BADDR (nDev) ; 
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/* for verify */ 
pstMEPList = pstMEArg->pstMEList; 


if((nFlag & ONLD_FLAG_ SYNC_MASK) == ONLD_FLAG_SYNC_OP) 
{ 
while (GET_ONLD_INT_STAT(nBAddr, PEND_ERASE) 
!= (UINT16) PEND_ERASE) 


/* Wait until device ready */ 
} 
pstPrevOpInfo[nDev]->ePreOp = NONE; 


for(nCnt = 0; nCnt < pstMEArg->nNumOfMList; nCnt+t+) 
{ 
/* Block Number Set */ 
ONLD_REG_START_ADDR1 (nBAddr) 
= (UINT16) MAKE FBA(pstMEPList [nCnt].nMEListPbn) ; 
ONLD_REG_START_ADDR2 (nBAddr) 
= (UINT16) MAKE DBS (pstMEPList [nCnt].nMEListPbn) ; 


/* Erase Verify Command issue */ 
ONLD_DBG_PRINT((TEXT("[ONLD:MSG] Erase Verify\r\n"))); 


/* INT Stat Reg Clear */ 
ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 


ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_ERASE_VERIFY; 


while (GET_ONLD_INT_STAT(nBAddr, PEND_INT) 
!'= (UINT16) PEND_INT) 


/* Wait until device ready */ 


} 

/* Erase Operation Verifying Error Check */ 

if (GET_ONLD_CTRL_STAT(nBAddr, ERROR_STATE) 
== ERROR_STATE) 


pstMEArg->nBitMapErr |= (1 << nCnt); 
nRet = LLD_MERASE_ERROR; 


return (nRet); 


SEE ALSO 
XXX_Read, XXX_Write, XXX_Erase, XXX_Copyback, XXX_MRead, 
XXX_MWrite, XXX_MErase 


XSR v1.5.1 Porting Guide 134 


SAMSUNG OMT 


XXX_CopyBack 


DESCRIPTION 


This function copies data by using internal buffer in the device. 


SYNTAX 


INT32 


XXX_CopyBack (UINT32 nDev, CpBkArg *pstCpArg, UINT32 nFlag) 


PARAMETERS 
Parameter Type 
nDev UINT32 
pstCpArg CpBkArg 
nFlag UINT32 


In/Out Description 


In Physical Device Number (0 ~ 7) 
In Pointer to CpBkArg data structure 
In Operation options (ECC on/off, Sync/Async) 


nFlag has the operaion options as follows. 


Flag Value Description 


LLD_FLAG_ASYNC_OP (1 <<0 


Asynchronous Operation 


) 
LLD_FLAG_SYNC_OP (0<<0) Synchronous Operation 
LLD_FLAG_ECC_ON (1<<1) ECC on (Read Operation with ECC) 
LLD_FLAG_ECC_OFF (0<<1) ECC off (Read Operation without ECC) 


Flag value is divided into Sync/Async Operation flag and ECC on/off flag. These two flags 


can be merged as follows. 


nFlag = LLD_FLAG SYNC_OP | LLD_FLAG_ECC_ON; 


RETURN VALUE 


Return Value 
LLD_SUCCESS 

LLD_READ_ ERROR ECC 
result code 

LLD_ WRITE ERROR 
LLD_PREV_WRITE_ ERROR 
| LLD_PREV_OP_RESULT 
LLD_PREV_ERASE_ ERROR 
| LLD_PREV_OP_RESULT 
LLD_TLLEGAL ACCESS 


REMARKS 


This function is mandatory. 


Description 
Copyback Success 
Data Integrity Fault (1 or 2bit ECC error) 


Write Operation Error 

In DCOP (Deferred Check Operation), previous write 
error happens 

In DCOP (Deferred Check Operation), previous erase 
error happens 

Illegal Copyback Operaion 


DCOP(Deferred Check Operation) : a method optimizing the operation performance. The 
DCOP method is a procedure to terminate the function (write or erase) right after the 
command issue. Then it checks the result of the operation at next function call. 
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Examples in this document do not implement the interrupt, because this Copyback example 
is implemented by calling Read and Write functions directly. If implementation of 
Copyback does not call Read and Write functions directly, codes which execute next steps 
must be added to support asynchoronous mode. First, check the value of a flag. And then, 
clear an interrupt. Finally, enable the interrupt. 


Copyback means the operation method to copy pages using the internal buffer in a NAND 
device. This copyback method improves the performance by cutting the transfer time and 
operation procedure, because this method does not use the external memory. When copying 
a page using the copyback method, a part of data can be brought the outside device; this is 
called Random-in. 


RndInArg and CpBkArg data structures are declared in XsrTypes.~h. 
O) RndInArg data structure 
| typedef struct 


i { i 
i UINT16 nOffset; /* nOffset : sector offset (0-3) *1024 | 


+ Main(0 - 511) + Spare (512 - 527) */ | 
UINT16 nNumOfBytes; /* Random In Bytes aye 
UINT8 =*pBuf; /* Data Buffer Pointer tf 


} RndInArg; 


Table 5-5 describes RndInArg data structure. 


Table 5-5. RndInArg data structure in XsrTypes.h 


Member Varilable Description 

nNumOfBytes The size of data to be changed 

nOffset The location of data to Random-in 
Offset : sector offset(0 - 3) * 1024+ Main(0 - 511) + Spare(512 - 
527) 

pBuf The pointer of data to be changed 


O CpBkArg data structure 


| typedef struct 
if 


UINT32 nsrcsn; /* Copy Back Source Vsn, shouldbe page i 
aligned */ i 

UINT32 nDstSn; /* Copy BackDest. Vsn, shouldbe page i 
aligned */ | 

UINT32 nRndInCnt; /* Random In Count */ | 

| RndInArg *pstRndInArg; /* RndInArg Array pointer xf 
| } CpBkArg; i 


Table 5-6 describes CpBkArg data structure. 


Table 5-6. CpBkArg data structure in XsrTypes.h 
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Member Varilable Description 
nSrcSn The location of a source page in NAND flash memory 
Physical sector number aligned at Physical page address 
nDstSn The location of data to be copied 
Physical sector number aligned at Physical page address 
nRndInCnt The count of Random-in 
pstRndiInaArg Pointer to RndInArg data structure 
EXAMPLE 


i #include 
: #include 
| #include 
| #include 


<XSRTypes.h> 
<PAM.h> 
<LLD.h> 


| BOOL32 
| Example (VOID) 
if 


(1) Example to call the function : 


<XXX.h> /* Header File of Low Level Device Driver fe 


aMBuf [XSR_MAIN_SIZE]; 
aSBuf [XSR_SPARE_SIZE]; 


LLD_FLAG_ASYNC_OP; 


return (FALSE32); 
} 


return (TRUE32); 


INT32 nErr; 

UINT32 nDev = 0; 

UINT32 nVol = 0; 

UINT8 

UINT8 

CpBkArg stCpArg; 
RndInArg stRIArg[2]; 
UINT32 nFlag = 
LowFuncTbl stLFT[MAX_VOL]; 
PAM RegLFT( (VOID *)stLFT); 


stCpArg.nSrcsSn = 32; 
stCpArg.nDstSn = 64; 
stCpArg.nRndInCnt = 2; 
stCpArg.pstRndInArg = &StRIArg[0]; 
stRIArg[0].nOffset = 0; 
stRIArg[0].nNumOfBytes = LLD_MAIN_SIZE; 
stRIArg[0].pBuf = &aMBuf [0]; 
stRIArg[1].nOffset = 512; 
stRIArg[1].nNumOfBytes = LLD_SPARE_SIZE; 
stRIArg[1] .pBuf = &aSBuf[0]; 
nErr = stLFT[nVol].CopyBack(nDev, &stCpArg, nFlag); 
if (nErr != LLD_SUCCESS) 
{ 

printf (“XXX_CopyBack()fail. ErrCode = %x\n”, nErr); 


(2) Example to implement the function in OneNAND 


| INT32 
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| ONLD_CopyBack (UINT32 nDev, CpBkArg *pstCpArg, UINT32 nFlag) | 
if 


UINT8 aBABuf [2]; 

UINT8 *pRIBuf; 

INT32 nSctNum, nOffset; 
UINT16 nBSA; 

UINT16 nEccRes; 

UINT16 nPbn; 

volatile UINT16 *pDevBuf; 

UINT32 nCnt; 

UINT32 *pONLDMBuf, *pONLDSBuf; 
UINT32 nBAddr; 

UINT32 nRISize; 

INT32 nRes; 


RndInArg *pstRIArg; 
nBAddr = GET_DEV_BADDR (nDev) ; 
if ((nRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 


{ 


return nRes; 


Die Sei sa */ 
/* Step 1. READ */ 
Sid Tee ee */ 


nPbn = GET_PBN(nDev, pstCpArg->nSrcSn) ; 


/* Block Number Set */ 


ONLD_REG_START_ADDR1 (nBAddr) = (UINT16)MAKE_ FBA(nPbn) ; 
/* Device BufferRam Select */ 
ONLD_REG_START_ADDR2 (nBAddr) = (UINT16)MAKE DBS (nPbn) ; 


/* Sector Number Set */ 

ONLD_REG_START_ADDR8 (nBAddr) = (UINT16) ( 
((pstCpArg->nSrcSn << astONLDInfo[nDev] .nFPASelSft) 
& MASK FPA) 
| (pstCpArg->nSrcSn & astONLDInfo[nDev] .nFSAMask) ); 


nBSA = (UINT16) MAKE _BSA(0, DATA_BUFO); 


ONLD_REG_START_BUF (nBAddr) = (UINT16) ( 
(nBSA & MASK_BSA) | (GET_SCTS_PER_PG(nDev) & MASK_BSC) ); 


PONLDMBuf 


(UINT32*) GET_ONLD_MBUF_ADDR ( 
nBAddr, 0, DATA BUFO); 
(UINT32*) GET_ONLD_SBUF_ADDR ( 
nBAddr, 0, DATA BUFO); 


pONLDSBuf 


ll 


if (nFlag & ONLD_FLAG_ECC_ON) 
{ 
/* System Configuration Reg set (ECC On) */ 
ONLD_REG_SYS_CONF1(nBAddr) &= CONF1_ECC_ON; 
} 


else 


{ 
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/* System Configuration Reg set (ECC Off) */ 
ONLD_REG_SYS_CONF1 (nBAddr) [= CONF 1_ECC_OFF; 
} 


/* INT Stat Reg Clear */ 


ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 

Peed se ecards seseee ee ee */ 
/* ONLD Read CMD is issued */ 
i ae ee ee */ 
/* Page Read Command issue */ 

ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_READ_PAGE; 


while (GET_ONLD_INT_STAT(nBAddr, PEND_READ) 
!'= (UINT16) PEND_READ) 


/* Wait until device ready */ 


if (nFlag & ONLD_FLAG_ECC_ON) 


nEccRes = ONLD_REG_ECC_STAT (nBAddr) ; 
if (nEccRes & ONLD_READ_UERROR_A) 
{ 

return (ONLD_READ_ ERROR | nEccRes) ; 


/* a a ee */ 
/* Step 2. DATA RANDOM IN * / 
/* ee es */ 


pstRIArg = pstCpArg->pstRndInArg; 


for (nCnt = 0 ; nCnt < pstCpArg->nRndInCnt ; nCnt++) 
{ 


nSctNum = (pstRIArg[nCnt].nOffset / 1024); 
nOffset = (pstRIArg[nCnt].nOffset % 1024); 


pRIBuf = pstRIArg[nCnt] .pBuf; 
nRISize = pstRIArg[nCnt] .nNumOfBytes; 


if (nOffset < ONLD_MAIN_ SIZE) 
{ 
/* byte align for 16 */ 
if ((nOffset % sizeof(UINT16)) != 0) 
{ 
pDevBuf =(volatile UINT16*) ( (UINT32) 
PONLDMBuf + (nSctNum * ONLD_MAIN_SIZE) 
+ nOffset - 1); 


* (volatile UINT16*) aBABuf = *pDevBuf; 
aBABuf[1] = *pRIBuf++; 
*pDevBuf = * (volatile UINT16*) aBABuf; 


if (--nRISize <= 0) 
{ 
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continue; 
ence 
} 
if ((nRISize % sizeof(UINT16)) != 0) 
pDevBuf = (volatile UINT16*) ( (UINT32) 


pONLDMBuf + (nSctNum * ONLD_MAIN_SIZE) 
+ nOffset + nRISize - 1); 


* (volatile UINT16*) aBABuf = *pDevBuf; 
aBABuf[0] = *(pRIBuf + nRISize - 1); 


*pDevBuf = * (volatile UINT16*) aBABuf; 
if (--nRISize <= 0) 
{ 


continue; 
} 


MEMCPY ( (UINT8*) ( (UINT32) i 
pONLDMBuf+ (nSctNum * ONLD_MAIN_SIZE) +nOffset), | 


pRIBuf, 
nRISize); 
} 
else 
{ 
if ((nOffset % sizeof(UINT16)) != 0) 
{ 
pDevBuf = (volatile UINT16*) ( (UINT32) 
pONLDSBuf + (nSctNum * ONLD_SPARE_SIZE) 
+ (nOffset - ONLD_MAIN_SIZE) - 1); 
* (volatile UINT16*) aBABuf = *pDevBuf; 
aBABuf[1] = *pRIBuf++; 
*pDevBuf = * (volatile UINT16*) aBABuf; 
if (--nRISize <= 0) 
{ 
continue; 
} 
nOffsett++; 
} 
if ((mRISize % sizeof(UINT16)) != 0) 
{ 
pDevBuf = (volatile UINT16*) ( (UINT32) 


pONLDSBuf + (nSctNum * ONLD_SPARE_SIZE) 
+ (nOffset - ONLD_MAIN_ SIZE) 
+ nRISize - 1); 


* (volatile UINT16*) aBABuf = *pDevBuf; 
aBABuf[0] = *(pRIBuf + nRISize - 1); 
*pDevBuf = * (volatile UINT16*) aBABuf; 


if (--nRISize <= 0) 
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continue; 


} 


MEMCPY ( (UINT8*) ( (UINT32) 
pONLDSBuf + (nSctNum * ONLD_SPARE_SIZE) 
+ (nOffset - ONLD_MAIN_SIZE)), 


pRIBuf, 
nRISize); 
} 
} 
Phe Eis Ba a a ee x / 
/* Step 3. WRITE * / 
JR ee es x / 


nPbn = GET_PBN(nDev, pstCpArg->nDstSn) ; 


/* Block Number Set */ 


ONLD_REG_START_ADDR1 (nBAddr) = (UINT16)MAKE_ FBA(nPbn) ; 

ONLD_REG_START_ADDR2 (nBAddr) = (UINT16)MAKE DBS (nPbn) ; 

/* Sector Number Set */ 

ONLD_REG_START_ADDR8 (nBAddr) = (UINT16) ( 
((pstCpArg->nDstSn << astONLDInfo[nDev] .nFPASelSft) 
& MASK_FPA) | 
| (pstCpArg->nDstSn & astONLDInfo[nDev] .nFSAMask)); | 


nBSA = (UINT16)MAKE_BSA(pstCpArg->nDstSn, DATA_BUFO) ; 


ONLD_REG_START_BUF (nBAddr) = (UINT16) ( 
(nBSA & MASK_BSA) | 
(GET_SCTS_PER_PG(nDev) & MASK_BSC)); 


if (nFlag & ONLD_FLAG_ECC_ON) 
{ 
/* System Configuration Reg set (ECC On) */ 
ONLD_REG_SYS_CONF1 (nBAddr) &= CONF1_ECC_ON; 
} 
else 


{ 
/* System Configuration Reg set (ECC Off) */ 


ONLD_REG_SYS_CONF'1 (nBAddr) = CONF 1_ECC_OFF; 
} 
ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 
i x / 
/* ONLD Write CMD is issued */ 
[PR ee ee ee ae x / 
/* Main Write Command issue */ 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_WRITE_PAGE; 
pstPrevOpInfo[nDev] ->ePreOp = CPBACK; 
pstPrevOpiInfo[nDev]->nPsn = pstCpArg->nDstSn; 
pstPrevOpInfo[nDev]->nScts = GET_SCTS_PER_PG (nDev) ; 
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pstPrevOpInfo[nDev]->nFlag = nFlag; 
pstPrevOpInfo[nDev] ->nBufSel = DATA BUFO; 


/* in case async mode, interrupt should be enabled */ 
if (nFlag & ONLD_FLAG_ ASYNC_OP) 
{ 


PAM ClearInt ( (UINT32) XSR_INT_ID_NAND_0); 
PAM EnableInt ( (UINT32) XSR_INT_ID_NAND_0); 


return (ONLD_SUCCESS) ; 


SEE ALSO 


XXX_Read, XXX_Write, XXX_Erase, XXX_MRead, 


XXX_MWrite, 
XXX_MErase, XXX_EraseVerify 
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XXX_ChkinitBadBlk 


DESCRIPTION 
This function checks whether a block is an initial bad block or not. 
SYNTAX 


INT32 
XXX_ChkInitBadBlk (UINT32 nDev, UINT32 nPbn) 


PARAMETERS 
Parameter Type In/Out Description 
nDev UINT32 In Physical Device Number (0 ~ 7) 
nPbn UINT32 In Physical Block Number 
RETURN VALUE 
Return Value Description 
LLD_SUCCESS Bad Block Check Success 
LLD_INIT_GOODBLOCK In a Good Block (Not a Bad Block) 
LLD_INIT_BADBLOCK In an Initial Bad Block 


LLD_PREV_WRITE_ERROR In DCOP (Deferred Check Operation), previous write 
| LLD_PREV_OP_RESULT _ error happens 

LLD_PREV_ERASE_ERROR In DCOP (Deferred Check Operation), previous erase 
| LLD_PREV_OP_RESULT _ error happens 

LLD_ILLEGAL_ACCESS Illegal Operation 


REMARKS 
This function is mandatory. 


DCOP(Deferred Check Operation) : a method optimizing the operation performance. The 
DCOP method is a procedure to terminate the function (write or erase) right after the 
command issue. Then it checks the result of the operation at next function call. 


If the value of the bad mark position in the first or second page of a block is not Oxff(a 
normal statement), the block is the initial bad block. 


EXAMPLE 


| #include <XSRTypes.h> 

: #include <PAM.h> 

i #include <LLD.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver */ | 


(1) Example to call the function 


| BOOL32 

| Example (VOID) 

if 

; INT32 nErr; 
UINT32 nDev = 0; 
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UINT32 nVol = 0; 
UINT32 nPbn = 0; 
LowFuncTbl stLFT[MAX_VOL]; 


PAM RegLFT( (VOID *)stLFT); 
nErr = stLFT[nVol].ChkInitBadBlk(nDev, nPbn); 


if (nErr != LLD_SUCCESS) 
printf (“XXX_ChkInitBadB1k () fail. ErrCode = %x\n"”, nErr); | 

return (FALSE32); : 

} 

return (TRUE32); 


(2) Example to implement the fuinction in OneNAND 
| INT32 i 


| ONLD_ChkInitBadB1k (UINT32 nDev, UINT32 nPbn) 
| { 

/ INT32 nRet; 

UINT16 aSpare[ONLD_SPARE_SIZE / 2]; 
UINT32 nPsn; 

UINT32 nBAddr; 


nBAddr = GET_DEV_BADDR (nDev) ; 
nPsn = nPbn * GET_SCTS_PER_BLK (nDev) ; 


nRet = ONLD_Read (nDev, /* Device Number */ 
nPsn, /* Physical Sector Number a | 
(UINT32)1, /* Number of Sectors to be read 2 | 
(UINT8*) NULL, i 
/* Buffer pointer for Main area */ | 
(UINT8*) aSpare, | 
/* Buffer pointer for Spare area */ | 
(UINT32) ONLD_FLAG ECC_OFF) ;/*flag */ 


if ((mRet != ONLD_SUCCESS) && ((nRet & (OxFFFFO0000) ) 
!= (UINT32) ONLD_READ_ERROR) ) 


{ 
return (nRet); 
} 
if (aSpare[0] != (UINT16) VALID_BLK_MARK) 
{ 
return (ONLD_INIT_BADBLOCK) ; 
} 


return (ONLD_INIT_GOODBLOCK) ; 


SEE ALSO 
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XXX_SetRWArea 


DESCRIPTION 


This function is called when NAND device provides write/erase protection functionality in 
hardware. 


SYNTAX 


INT32 
XXX_SetRWArea (UINT32 nDev, UINT32 nlstUB, UINT32 nNumOfUBs) 


PARAMETERS 
Parameter Type In/Out Description 
nDev UINT32 In Physical Device Number (0 ~ 7) 
nlstUB UINT32 In Start block index of unlocked area 
nNumOfUBs UINT32 In Total number of blocks of unlocked area 
nNumOfUBs = 0, the device is locked. 
RETURN VALUE 
Return Value Description 
LLD_SUCCESS Unlock Aea Setting Success 
LLD_TILLEGAL ACCESS Illegal Setting 
REMARKS 


This function is optional. 


If the hardware does not provide write/erase protection functionality in hardware, a user 
does not need to implement this function. 


EXAMPLE 


: #include <XSRTypes.h> 

| #include <PAM.h> 

i #include <LLD.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver *] | 


(1) Example to call the function ; 


| BOOL32 
| Example (VOID) 
if 


INT32 nErr; 

UINT32 nDev = 0; 
UINT32 nVol = 0; 
UINT32 nlstUB = 0; 
UINT32 nNumOfUBs = 1024; 


LowFuncTbl stLFT[MAX_VOL]; 


PAM RegLFT((VOID *)stLFT); 


XSR v1.5.1 Porting Guide 145 


SAM SUG D000 Tat 


aver bne eb lawiled 


nErr = stLFT[nVol].SetRWArea(nDev, nlstUB, nNumOfUBs) ; 


if (nErr != LLD_SUCCESS) 

{ 
printf (“XXX_ SetRWArea()fail. ErrCode = %x\n"”, nErr); 
return (FALSE32); 


} 
return (TRUE32); 


(2) Example to implement the function in OneNAND ; 


| INT32 
| ONLD_SetRWArea (UINT32 nDev, UINT32 nSUbn, UINT32 nUB1lks) 
i { 
| INT32 nRes; 
if ((nRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 
{ 


pstPrevOpInfo[nDev]->ePreOp = NONE; 
return nRes; 


} 
if (astONLDInfo[nDev].SetRWArea != NULL) 
{ 
astONLDInfo[nDev] .SetRWArea(nDev, nSUbn, nUBI1ks); 
} 
else 
{ 
return (ONLD_ILLEGAL ACCESS) ; 
} 


return (ONLD_SUCCESS) ; 


SEE ALSO 


XSR v1.5.1 Porting Guide 146 


SAMSUNG OMT 


XXX_lIOCtI 


DESCRIPTION 
This function is called to extend LLD functionality. 
SYNTAX 


INT32 

XXX_IOCt1(UINT32 nDev, UINT32 nCode, UINT8 *pBufI, 
UINT32 nLenI, UINT8 *pBufO, UINT32 nlLeno, 
UINT32 *pByteRet) 


PARAMETERS 
Parameter Type In/Out _ Description 
nDev UINT32 In Physical Device Number (0 ~ 7) 
nCode UINT32 In IO Control Command 
pBufI UINT8 * In Input Buffer pointer 
nLenI UINT32 In Length of Input Buffer 
pBufo UINT8 * Out Output Buffer pointer 
nLenO UINT32 In Length of Output Buffer 
pByteRet UINT32 * Out The number of bytes (length) of Output 
Buffer as the result of function call 
RETURN VALUE 
Return Value Description 
LLD_SUCCESS Success 
LLD_IOC_NOT_SUPPORT In not-supported command 
REMARKS 


This function is optional. 


DCOP(Deferred Check Operation) : a method optimizing the operation performance. The 
DCOP method is a procedure to terminate the function (write or erase) right after the 
command issue. Then it checks the result of the operation at next function call. 


The following list is IO control code command. 
- LLD_IOC_SET_SECURE_LT 
- LLD_IOC_SET_BLOCK_LOCK 


- LLD_IOC_GET_SECURE_STAT 
- LLD_IOC_RESET_NAND_DEV 


The following explains the description, parameters, and return value of each IO control 
code. 
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LLD_IOC_SET_SECURE_LT 


1. Description 


If NAND flash memory supports the lock scheme, this command code lock-tighten the 
current lock statement. 

If NAND flash memory does not support the lock scheme, this command returns 
LLD_ILLEGAL_ACCESS 


2. Parameter 


Parameter Description 

nDev Physical Device Number (0 ~ 7) 

nCode LLD_TOC_SET_SECURE_LT 

pBufIl Pointer to Start Block Number and Number of 


Blks if Lock Block device is used. 
Not used if Lock Range device is used 


nLenI Length of Input Buffer if Lock Block device is 
used 
Not used if Lock Range device is used 

pBufo Not used 

nLeno Not used 

pByteRet This value is set as 0 in XXX_IOCt1. 


3. Return Value 


Return Value Description 
LLD_SUCCESS Lock-tighten the current lock statement 


LLD_IOC_SET_BLOCK_LOCK 


1. Description 


If NAND flash memory supports the lock scheme, this command code locks the blocks 
given in pBufl. 


2. Parameter 


Parameter Description 

nDev Physical Device Number (0 ~ 7) 

nCode LLD_TOC_SET_SECURE_LT 

pBufl Pointer to Start Block Number and Number of 
Blks 

nLenI Length of Input Buffer 

pBufo Not used 

nLeno Not used 

pByteRet This value is set as 0 in XXX_IOCt1. 
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3. Return Value 
Return Value Description 
LLD_SUCCESS Lock the blocks given in pBufl 


LLD_IOC_GET_SECURE_STAT 


1. Description 


If NAND flash memory supports the lock scheme, this command code gets the current lock 
statement. The current lock statement is saved at pBufoO. 

If NAND flash memory does not support the lock scheme, the current lock statement is 
LLD_TIOC_SECURE_US. 


2. Parameter 


Parameter Description 

nDev Physical Device Number (0 ~ 7) 

nCode LLD_TIOC_GET_SECURE_STAT 

pBufI Not used 

nLenI Not used 

pBufO Buffer to store return value 

nLeno Length of pBufO 

pByteRet This value is set as output buffer length in 
XXX_IOCtl. 


3. Return Value 


Return Value Description 

LLD_SUCCESS Get the current lock statement 

LLD_ILLEGAL_ACCESS The value of pBufO or nLenO parameter is abnormal 
4, Remark 


There are three values of the lock statement. The lock statement is declared in LLD.h. 
The following describes each lock statement. 


LLD_IOC_SECURE_LT is that the locked block of NAND flash memory is 
lock-tightened. 
The block cannot be changed to unlocked or locked by software. 


LLD_IOC_SECURE_LS is that all block of NAND flash memory is locked. 
All block can be read and cannot be written or erased. 


LLD_IOC_SECURE_US is that the sequential block of NAND flash memory is unlocked. 


The unlocked sequential block can be read/written/erased. 
The locked block keeps the locked statement, so it cannot be read/written/erased. 
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LLD_IOC_RESET_NAND_DEV 


1. Description 


This control command resets NAND flash memory. 


2. Parameter 


Parameter Description 

nDev Physical Device Number (0 ~ 7) 

nCode LLD_TOC_RESET_NAND_DEV 

pBufI Not used 

nLenI Not used 

pBufo Not used 

nLeno Not used 

pByteRet This value is set as 0 in XXX_IOCtl. 


3. Return Value 


Return Value Description 
LLD_SUCCESS Reset NAND flash memory 
EXAMPLE 


| INT32 

| ONLD_IOCt1(UINT32 nDev, UINT32 nCode, 
i UINT8 *pBufl, UINT32 nLenI, 
UINT8 *pBufO, UINT32 nLeno, 
UINT32 *pByteRet) 


(1) Example to implement the function in OneNAND ; 


INT32 nRet; 
UINT32 nBAddr; 
UINT16 nRegVal; 
INT32 nRes; 


if (pByteRet == NULL) 
{ 

return (ONLD_ILLEGAL ACCESS) ; 
} 


nBAddr = GET_DEV_BADDR (nDev) ; 


if ((nRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 
{ 
return nRes; 


} 
switch (nCode) 


{ 
case LLD_IOC_SET_SECURE_LT: 
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if (astONLDInfo[nDev] .LockTight != NULL) : 
astONLDInfo[nDev] .LockTight (nDev, pBufI, nLenI); 
else 
return (ONLD_ILLEGAL ACCESS) ; 
*pByteRet = (UINT32) 0; 
nRet = ONLD_SUCCESS; 
break; 


case LLD_IOC_SET_BLOCK_LOCK: 


if (_LockBlock(nDev, pBufI, nLenI) != ONLD_SUCCESS) 


{ 
return (ONLD_ILLEGAL_ ACCESS) ; 


} 


*pByteRet = (UINT32) 0; 
nRet = ONLD_SUCCESS; 
break; 


case LLD_IOC_GET_SECURE_STAT: 
if ((pBufO == NULL) || (nLeno < 2)) 
{ 
return (ONLD_ILLEGAL ACCESS) ; 
} 
nRegVal = ONLD_REG_WR_PROTECT_STAT (nBAddr) ; 
MEMCPY (pBufO, &nRegVal, sizeof (UINT16) ); 


*pByteRet = (UINT32) 2; 
nRet = ONLD_SUCCESS; 
break; 


case LLD_IOC_RESET_NAND_DEV: 


if ((GET_DEV_DID(nDev) & 0x0008) == DDP_CHIP) 
{ 
ONLD_REG_START_ADDR1 (nBAddr) = (UINT16) (0x0000); | 
ONLD_REG_START_ADDR2 (nBAddr) = (UINT16) (0x0000) ; 


ll 


ONLD_REG_INT(nBAddr) = (UINT16) INT_CLEAR; 

[ised setecaseeseueeseeewasasas */ 

/* ONLD Unlock CMD is issued if 

ae ee ee eee */ 
ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_RESET; 


while (GET_ONLD_INT_STAT(nBAddr, PEND_RESET) 
!'= (UINT16) PEND_RESET) 


/* Wait until device ready */ 


} 


ONLD_REG_ START _ADDR1(nBAddr) = (UINT16) (0x8000); | 
ONLD_REG_START_ADDR2 (nBAddr) (UINT16) (Ox8000); : 
} /*if DDP_CHIP */ 


ONLD_REG_INT (nBAddr) = (UINT16) INT_CLEAR; 
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Pee ee eee */ 
/* ONLD Unlock CMD is issued */ 
Pie Sees ee eee ee */ 


ONLD_REG_CMD (nBAddr) = (UINT16) ONLD_CMD_RESET; 


while (GET_ONLD_INT_STAT(nBAddr, PEND_RESET) 
!'= (UINT16) PEND_RESET) 


/* Wait until device ready */ 


} 


*pByteRet = (UINT32) 0; 
nRet = ONLD_SUCCESS; 
break; 


default: 
nRet = ONLD_IOC_NOT_SUPPORT; 
break; 
} 


return nRet; 


SEE ALSO 
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XXX_GetPrevOpData 


DESCRIPTION 


This function copies data of previous write operation to the given buffer. This function is 
called to rewrite the block in the error case of the previous write operation. 


SYNTAX 


INT32 
XXX_GetPrevOpData (UINT32 nDev, UINT8 *pMBuf, UINT8 *pSBuf) 


PARAMETERS 
Parameter Type In/Out Description 
nDev UINT32 In Physical Device Number (0 ~ 7) 
pMBuf UINT8 * Out Memory buffer for main array of NAND 
flash memory 
psBuf UINT8 * Out Memory buffer for spare array of NAND 
flash memory 
RETURN VALUE 
Return Value Description 
LLD_SUCCESS Copy Success 
LLD_ILLEGAL_ACCESS Illegal access 
REMARKS 


This function is an optional Deferred Check Operation function. 


DCOP(Deferred Check Operation) : a method optimizing the operation performance. The 
DCOP method is a procedure to terminate the function (write or erase) right after the 
command issue. Then it checks the result of the operation at next function call. 


EXAMPLE 


| #include <XSRTypes.h> 

| #include <PAM.h> 

| #include <LLD.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver */ 


(1) Example to call the function 


| BOOL32 
| Example (VOID) 
if 


INT32 nErr; 

UINT32 nDev = 0; 

UINT32 nVol = 0; 

UINT8 aMBuf [LLD_MAIN_SIZE]; 
UINT8 aSBuf [LLD_SPARE_ SIZE]; 


LowFuncTbl stLFT[MAX_VOL]; 
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PAM _RegLFT((VOID *)stLFT); i 
nErr = stLFT[nVol].GetPrevOpData(nDev, aMBuf, aSBuf); 


if (nErr != LLD_SUCCESS) 

t i 
printf (“XXX_GetPrevOpData() fail. ErrCode = %x\n"”, nErr); | 

return (FLASE32); : 

} 

return (TRUE32); 


(2) Example to implement the function in OneNAND 
| INT32 i 
| ONLD_Get PrevOpData (UINT32 nDev, UINT8 *pMBuf, UINT8 *pSBuf) 

if 
i UINT32 nBAddr; 

UINT32 nPbn; 

UINT32 *pONLDMBuf, *pONLDSBuf; 


nBAddr = GET_DEV_BADDR(nDev) ; 
if ((pMBuf == NULL) && (pSBuf == NULL)) 
{ 
return (ONLD_ILLEGAL_ACCESS) ; 
} 


nPbn = GET_PBN(nDev, pstPrevOpiInfo[nDev]->nPsn) ; 
ONLD_REG_START_ADDR2 (nBAddr) = (UINT16)MAKE DBS (nPbn) ; 


PpONLDMBuf 


(UINT32*) GET_ONLD_MBUF_ADDR ( 
nBAddr, 
pstPrevOpiInfo[nDev]->nPsn, 
GET_CUR_BUF_SEL(nDev) ); 


PONLDSBuf = (UINT32*) GET_ONLD_SBUF_ADDR ( 
nBAddr, 
pstPrevOpInfo[nDev]->nPsn, 
GET_CUR_BUF_SEL (nDev) ) ; 

[Rose hd ewes See Soe Se ee ee re ee a x / 

/* Data is loaded into Memory * / 

PR a a a ee el eee x / 

if (pMBuf != NULL) 


/* Memcopy for main data */ 
MEMCPY (pMBuf, pONLDMBuf, 
(ONLD_MAIN_SIZE * pstPrevOpInfo[nDev]->nScts) ); 
if (pSBuf != NULL) 
/* Memcopy for spare data */ 


MEMCPY (pSBuf, pONLDSBuf, i 
(ONLD_SPARE_ SIZE * pstPrevOpInfo[nDev]->nScts)); | 


return (ONLD_SUCCESS) ; 


XSR v1.5.1 Porting Guide 154 


SAMSUNG DOG Tail 


averpena’ ib liviied. 


E 


SEE ALSO 
XXX_FlushoOp 
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XXX_FlushOp 


DESCRIPTION 
This function completes the current working operation. 
SYNTAX 


INT32 
XXX_FlushOp (UINT32 nDev) 


PARAMETERS 

Parameter Type In/Out Description 

nDev UINT32 In Physical Device Number (0 ~ 7) 
RETURN VALUE 

Return Value Description 

LLD_SUCCESS Success 

LLD_ILLEGAL_ACCESS Illegal Access 


LLD_PREV_WRITE_ERROR In DCOP (Deferred Check Operation), previous write 
| LLD_PREV_OP_RESULT _ error happens 
LLD_PREV_ERASE_ERROR In DCOP (Deferred Check Operation), previous erase 
| LLD_PREV_OP_RESULT __ error happens 


REMARKS 
This function is an optional Deferred Check Operation function. 


EXAMPLE 


i #include <XSRTypes.h> 

| #include <PAM.h> 

| #include <LLD.h> 
i #include <XxX.h> /* Header File of Low Level Device Driver */ | 


(1) Example to call the function ; 


| BOOL32 
| Example (VOID) 
| { 


INT32 nErr; 
UINT32 nDev = 0; 
UINT32 nVol = 0; 


LowFuncTbl stLFT[MAX_VOL]; 

PAM RegLFT( (VOID *)stLFT); 

nErr = stLFT[nVol].FlushOp (nDev) ; 
if (nErr != LLD_SUCCESS) 


{ 
printf (“XXX_ FlushOp()fail. ErrCode = %x\n”, nErr); 
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return (FALSE32); 
} 
return (TRUE32); 


(2) Example to implement the function in OneNAND 
| INT32 

| ONLD_FlushOp (UINT32 nDev) 

| { 

! UINT32 nBAddr; 

INT32 nRes; 


nBAddr = GET_DEV_BADDR (nDev) ; 


if ((nRes = _ChkPrevOpResult (nDev)) != ONLD_SUCCESS) 
{ 
return nRes; 


} 


return (ONLD_SUCCESS) ; 


SEE ALSO 
XXX_GetPrevOpData 
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PAM (Platform Adaptation 
Module) 


6.1. 


This chapter describes the definition, system architecture, features, and APIs of PAM. 


Description & Architecture 


PAM is an abbreviation of Platform Adaptation Module. PAM links XSR with the platform. 
PAM is responsible for the platform-dependent part of XSR layer (STL, and BML). If the 
platform is changed, a user only changes PAM. 


@ Reference 

Generally, the platform is underlying the computer system on which application program 
can run. This document calls the platform is the board that consists of CPU, DRAM, 
NAND flash memory, etc. 


For example, a layer of XSR wants to requests the volume and device information of 
NAND flash memory. The requested information is dependent on the platform. Each layer 
calls an adaptation module PAM to use the platform functionalities. Therefore, a user must 
implement PAM suitable for the platform when a user ports XSR. 


Figure 6-1 shows PAM in XSR system architecture. 
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File System 
| 


Block Device Interface 


Logical Flash Address 


XSR Core 


Sector Translation Layer 


| Virtual Flash Address 


OS Adaptation 
Module 


Block Management Layer 


Physical Flash Address 


Low Level Device Driver 


NAND Flash Memory 
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Figure 6-1. PAM in XSR System Architecture 


PAM has 9 functions that are classified into 4 categories as follows. 
0 Initialization function : hardware initialization 


O Device Configuration functions : LFT registration, and XSR and LLD information 
return 


O Interrupt functions : interrupt initialization, interrupt bind, interrupt enable, interrupt 
disable, and interrupt clear 


OO Memory Operation function : memory copy 


In the next chapter, PAM APIs are covered in detail. 
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6.2. API 


This chapter describes PAM APIs. 


@ Reference 


All the PAM function has a prefix “PAM_” on each function name. 


Table 6-1 shows the lists of PAM APIs. 

The right row in table shows that the function is Mandatory or Optional or Recommended. 
Optional functions should be existed, but contents of the functions does not need to be 
implemented. 


Table 6-1. PAM API 


Function Description 

PAM Init This function initializes NAND specific hardware O 
PAM _GetPAParm This function maps the platform and device. M 
PAM RegLFT This function registers LLD to XSR. M 
PAM _InitInt This function initializes the interrupt for NAND device. O 
PAM BindInt This function binds the interrupt for NAND device. oO 
PAM _EnableInt This function enables the interrupt for NAND device. O 
PAM DisableInt | This function disables the interrupt for NAND device. O 
PAM ClearInt This function clears the interrupt for NAND device. O 
PAM _Memcpy This function copies data from source to destination M 
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PAM Init 


DESCRIPTION 


This function initializes NAND specific Hardware. 


SYNTAX 


VOID 
PAM Init (VOID) 


PARAMETERS 
None 

RETURN VALUE 
None 


REMARKS 


This function performs platform specific initialization for allowing access to NAND flash 
device. If necessary, this function should initialize memory bus width, and memory 
configuration registers for NAND flash device. 


EXAMPLE 


(1) Example to call the function 
| #include <PAM.h> 
| #include <XSRTypes.h> 


| VOID 

| Example (VOID) 
if 
| /* PAM_Init() should be called at open time */ 
PAM Init(); 


/* LLD Function Table initialization */ 
j PAM _RegLFT (gstLFT) ; 
i} 


(2) Example to implement the function in S3C2410 
! VOID 
| PAM_Init (VOID) 
| 
i} 


SEE ALSO 
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PAM_GetPAParm 


DESCRIPTION 
This function maps the platform and device. 
SYNTAX 


VOID* 
PAM GetPAParm (VOID) 


PARAMETERS 
None 
RETURN VALUE 
Return Value Description 
VOID * Returns the address of the array having information 
about the volume and device 
REMARKS 


This function is mandatory. 


Currently, XSR supports two volumes and eight devices at maximum, because the number 
of maximum volume (XSR_MAX_VOL) is defined as 2 and the number of maximum device 
(XSR_MAX_DEV) is defined as 8 in XSRTypes. When calling PAM_GetPAParm, a user 
can get the volume and device information together. So, a user gets the platform 
information by calling PAM_GetPAParm. 


XsrVolParm data structure is declared in PAM.h. 


Ol XsrVolParm data structure 


| typedef struct { 
| UINT32 nBaseAddr [XSR_MAX_DEV/XSR_MAX_VOL]; 
/* the base address for accessing NAND device*/ 


UINT16 nEccPol; 
/* Ecc Execution Section 
NO_ECC : No ECC or ECC execution by 
another type of ECC algorithm 
SW_ECC : ECC execution by XSR Software 
(based on Hamming code) 
HW_ECC : ECC execution by HW 
(if HW has ECC functionality 
based on Hamming code) */ 


UINT16 nLSchemePol; 


/* Lock Scheme Policy Section 
NO_LOCK_SCHEME : No Lock Scheme 
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SW_LOCK_SCHEME : Lock Scheme Execution by SW 
HW_LOCK_SCHEME : Lock Scheme Execution by HW i 
(if HW has Lock/Unlock functionality) */ } 


BOOL32 bByteAlign; 
/* Memory Byte Alignment Problem 
TRUE32 : Byte Align Problem Free in XSR and LLD 
(Memory usage increased) 
FALSE32 : No Action for Byte Align Problem */ 


UINT32 nDevsInVol; 
/* number of devices in the volume */ 


VOID *pExInfo; 
/* For Device Extension. For Extra Information of Device, 
data structure can be mapped. */ 


} XsrVolParm; 
More detailed explanation about XsrVolParmis as follow. 
O nBaseAddr is a base address of NAND device for LLD. 


O nEccPol is a policy whether using ECC code or not: nEccPol can be HW_ECC, 
SW_ECC and NO_ECC. A user sets as HW_ECC when NAND device provides ECC 
generation/correction based on Hamming code. In that case, spare assignment for generated 
ECC code should be compatible with Samsung spare assignment standard. A user sets as 
NO_ECC when NAND device uses no ECC algorithm or hardware ECC algorithm which is 
not compatible with Samsung standards®. When a user wants to use software ECC 
supported by XSR and sets as SW_ECC, BML handles ECC generation/correction. For more 
information about the ECC policy, refer to Chapter 7.6 ECC Policy. 


O nLSchemePol is a policy related to write/erase protection: nLSchemePol can be 
HW_LOCK_SCHEME, SW_LOCK_SCHEME, and NO_LOCK_SCHEME. A user sets as 
NO_LOCK_SCHEME when NAND device does not provide the lock scheme, and sets as 
HW_LOCK_SCHEME when NAND device use the lock scheme. When a user wants to use 
the lock scheme in software and sets as SW_LOCK_SCHEME , BML handles the write/erase 
protection. 


Ol bByteAlign is used to decide whether LLD fits the alignment or not, when LLD gets 
not-aligned buffer from the upper layer in read/write operation. A users set as TRUE32_ that 
means to fit the alignment, while a user sets as FALSE32 that means to hand it over LLD, 
although it is not-aligned. 


O nDevsInVol1 is the number of the allocated device in the volume. 


O pExInfo is entry for extension usage. It is available for developers who want to add 
their own platform dependent information. 


° Memory Division, Samsung Electronics Co., Ltd, “ECC(Error Checking & Correction) Algorithm”, 
http://www.samsung.com/Products/Semiconductor/Flash/TechnicalInfo/eccalgo_040624.pdf 


Memory Division, Samsung Electronics Co., Ltd, *"NAND Flash Spare Assignment recommendation”, 
http://www.samsung.com/Products/Semiconductor/Flash/TechnicalInfo/Spare_assignment_recommendation.pd 


f 
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EXAMPLE 


| #include <PAM.h> 
| #include <XSRTypes.h> 


| VOID 
| Example (VOID) 
| { 


pstPAM = 


(XsrVolParm *) 


XsrVvolParm *pstPAM; 


| #include <XSRTypes.h> 
| #include <PAM.h> 
| #include <XXX.h> 


| #define 


VOLO 
/#define  VOL1 
| #define DEVO 
| #define DEV1 
| #define DEV2 
| #define DEV3 
| VOID* 


(1) Example to call the function : 


PAM GetPAParm(); 


(2) Example to implement the function in S3C2410 ; 


/* Header File of Low Level Device Driver et 


WNrR OO 


| PAM_Get PAParm (VOID) 


gstParm[VOLO] 
gstParm[VOLO] 
gstParm[VOLO] 
gstParm[VOLO] 


gstParm[VOLO] 
gstParm[VOL0O] 
gstParm[VOLO] 
gstParm[VOLO] 
gstParm[VOLO] 


gstParm[VOL1] 
gstParm[VOL1] 
gstParm[VOL1] 
gstParm[VOL1] 


gstParm[VOL1] 
gstParm[VOL1] 
gstParm[VOL1] 
gstParm[VOL1] 
gstParm[VOL1] 


return 


(VOID *) 


.-nBaseAddr [DEVO] 
-nBaseAddr [DEV1] 
.-nBaseAddr [DEV2] 
.-nBaseAddr [DEV3] 


-nEccPol 
-nLSchemePol 
-bByteAlign 
-nDevsInVol 
-pExInfo 


.-nBaseAddr [DEVO] 
-nBaseAddr [DEV1] 
.-nBaseAddr [DEV2] 
.-nBaseAddr [DEV3] 


-nEccPol 
-nLSchemePol 
-bByteAlign 
-nDevsInVol 
-pExInfo 


gstParm; 


0x20000000; 
NOT_MAPPED; 
NOT_MAPPED; 
NOT_MAPPED; 


SW_ECC; 
SW_LOCK_SCHEME; 
TRUE32; 

1; 

NULL; 


NOT_MAPPED; 
NOT_MAPPED; 
NOT_MAPPED; 
NOT_MAPPED; 


HW_ECC; 
HW_LOCK_SCHEME; 
TRUE32; 

0; 
NULL; 
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SEE ALSO 
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PAM_RegLFT 


DESCRIPTION 
This function registers functions to XSR. 
SYNTAX 


VOID 
PAM RegLFT (VOID *pstFunc) 


PARAMETERS 


Parameter Type In/Out Description 
pstFunc VOID * Out Pointer to LowFuncTbl data structure 


RETURN VALUE 
None 
REMARKS 


This function is mandatory. 


1. Registering LLD address to BML 


Each address 
is mapped 


Dev #0 Dev #1 Dev #7 


LLD1 LLD 2 LLD 3 


Functions 


Figure 6-2. Register LLD Address to BML 


BML encapsulates the various device driver(LLD)s. LFT(LLD Function Table) is a list of 
17 functions that is encapsulated by BML. LFT is defined at LLD.h as LowFuncTDbl. 
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0 LowFuncTbl data structure 


| typedef struct { 


INT32 (*Init) (VOID *pParm) ; 

INT32 (*Open) (UINT32 nDev); 

INT32 (*Close) (UINT32 nDev); 

INT32 (*Read) (UINT32 nDev, UINT32 nPsn, UINT32 nScts, 
UINT8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag) ; 

INT32 (*Write) (UINT32 nDev, UINT32 nPsn, UINT32 nScts, 
UINTS8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag) ; 

INT32 (*MRead) (UINT32 nDev, UINT32 nPsn, UINT32 nScts, 
SGL *pstSGL, UINT8 *pSBuf, UINT32 nFlag); 

INT32 (*MWrite) (UINT32 nDev, UINT32 nPsn, UINT32 nScts, 


SGL *pstSGL, UINT8 *pSBuf, UINT32 nFlag, 
UINT32 *pErrPsn); 

INT32 (*CopyBack) (UINT32 nDev, CpBkArg *pstCpArg, 
UINT32 nFlag); 


INT32 (*Erase) (UINT32 nDev, UINT32 Pbn, UINT32 nFlag); 

INT32 (*GetDeviInfo) (UINT32 nDev, LLDSpec *pstDeviInfo); 

INT32 (*ChkInitBadBlk) (UINT32 nDev, UINT32 Pbn); 

INT32 (*FlushOp) (UINT32 nDev); i 

INT32 (*SetRWArea) (UINT32 nDev, UINT32 nSUbn, UINT32 nUBlks); | 

INT32 (*GetPrevOpData) (UINT32 nDev, UINT8 *pMBuf, i 
UINT8 *pSBuf) ; 

INT32 (*IOCt1) (UINT32 nDev, UINT32 nCmd, 


UINT8 *pBufI, UINT32 nlLenlI, 
UINT8 *pBufO, UINT32 nLeno, 
UINT32 *pByteRet) ; 
INT32 (*MErase) (UINT32 nDev, LLDMEArg *pstMEArg, 
UINT32 nFlag); 
INT32 (*EraseVerify) (UINT32 nDev, LLDMEArg *pstMEArg, 
UINT32 nFlag); 


i} LowFuncTbl; 
LowFuncTb1 is allocated corresponding to each device and is able to support up to 8. 
Thus, it is necessary to register the function of real LLD to the corresponding 


LowFuncTbl. 


XSR can work together by calling PAM_RegLFT and registering the implemented LLD 
function. BML can call the real LLD function using the function pointer defined at LFT. 


pstFunc isa pointer of LowFuncTbl, a LLD address table. 
When BML calls PAM_RegLFT, it finds the real function address to access NAND device 
using LFT. 


2. Defining the volume and device of BML 
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Volume #0 Volume #1 


Device] Device} Device] Device Device | Device J Device § Device 
#0 #1 #2 #3 #4 #6 #7 


Figure 6-3. Define Volume and Device of BML 
A user must recognize the definition of a volume and device to use BML. XSR can support 
the device up to eight, and BML can manage several devices once bind them with a volume. 


BML can support the plural volumes, but it currently supports 2 volumes. BML binds the 
maximum four devices with a volume, and the devices must be the same type in a volume. 
For example, the device number #0 ~ #3 and #4 ~ #7 must be the same type of LLD. 


A user should know this volume and device features at BML, so a user can understand the 
mapping from BML to LLD using LFT. 


EXAMPLE 


ne3) Example to call the function ; 


i #include <PAM.h> 
| #include <XSRTypes.h> 


| VOID 

| Example (VOID) 
lf 

i PAM _Init(); 


/* LLD Function Table initialization */ 
PAM_RegLFT (gstLFT) ; 


(2) Example to implement the function in S3C2410 : 


_#include <XSRTypes.h> 
| #include <PAM.h> i 
| #include <XXX.h> /* Header File of Low Level Device Driver 7 a | 


|#define VOLO 0 
| VOID 


| PAM_RegLFT (VOID *pstFunc) 


| { 
i LowFuncTbl *pstLFT; 
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SEE ALSO 


pstLFT = 


pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 
pstLFT [VOLO] 


(LowFuncTb1*) pstFunc; 


Pl 9 

-Open 

-Close 

.Read 

-Write 

- CopyBack 
.Krase 
.GetDevinfo 
-ChkInitBadBlk 
-FlushOp 
.setRWArea 
.GetPrevOpData 
-loctl 

.MRead 

-MWrite 
.MErase 
.-EraseVerify 


COOOOOOCCOCOCOOC OO 


22Z 


NLD_Init; 


LD_Open; 
LD_Close; 
LD_Read; 
LD_Write; 
LD_CopyBack; 
LD_Erase; 
LD_GetDeviInfo; 
LD_ChkInitBadB1lk; 
LD_FlushOp; 
LD_SetRWArea; 
LD_GetPrevOpData; 
LD_IOCt1; 
LD_MRead; 


ONLD_MWrite; 
ONLD_MErase; 
ONLD_EraseVerify; 
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PAM_Initint 


DESCRIPTION 
This function initializes the specified logical interrupt. 
SYNTAX 


VOID 
PAM InitInt (UINT32 nLogIntId) 


PARAMETERS 


Parameter Type In/Out Description 
nLogIntId UINT32 In Logical interrupt ID number 


RETURN VALUE 
None 
REMARKS 


This function is an optional interrupt function. 
Currently, this function is used for asynchronous operation. 


This function set registers to use interrupts of platform. This function initializes the 
specified logical interrupt through OS dependent interrupt initialization function. 


EXAMPLE 


(1) Example to call the function : 


i #include <PAM.h> 
| #include <XSRTypes.h> 


| #define INT_ID_NAND_O (0) /* Interrupt ID : 1st NAND */ | 
| VOID 
| Example (VOID) 


Lf 
i /* initializes interrupt for lst NAND device */ 
PAM_InitInt ( (UINT32) INT_ID_NAND_0) ; 


/* initializes interrupt for lst NAND device */ 
PAM BindtInt ( (UINT32) INT_ID_NAND_0); 


(2) Example to implement the function in S3C2410 
| VOID i 
| PAM_InitInt (UINT32 nLogIntId) 
| { 
i switch (nLogIntId) 
{ 

case XSR_INT_ID_NAND_0: 
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TS3C2440::GPIO::SelectSignalMethod (EExtInt4, 
ERisingEdgeSignal) ; 


break; 
| default: 
| break; 
| 
OAM _InitInt (nLogIntId); 
3 
SEE ALSO 


PAM BindInt, PAM EnableInt, PAM _DisableInt, PAM _ClearInt 
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PAM_Bindint 


DESCRIPTION 


This function binds the specified logical interrupt for NAND device. 


SYNTAX 


VOID 
PAM BindInt (UINT32 nLogIntId) 


PARAMETERS 


Parameter Type In/Out Description 
nLogIntId UINT32 In Logical interrupt ID number 


RETURN VALUE 
None 
REMARKS 


This function is an optional interrupt function. 
Currently, this function is used for asynchronous operation. 


This function translates the specified logical interrupt ID into the physical interrupt ID and 
binds the interrupt through OS dependent function which binds interrupt. 


EXAMPLE 


(1) Example to call the function , 


| #include <PAM.h> 
| #include <XSRTypes.h> 


| #define INT_ID_NAND_O (0) /* Interrupt ID : 1st NAND */ | 


| VOID 

| Example (VOID) 
if 
i /* initializes interrupt for lst NAND device */ 
PAM _InitInt ((UINT32) INT_ID_NAND_0); 


/* initializes interrupt for lst NAND device */ 
i PAM BindtInt ((UINT32) INT_ID_NAND_0); 
i} 


(2) Example to implement the function in S3C2410 
| VOID | 
| PAM_BindInt (UINT32 nLogIntId) 


| { 
; UINT32 nPhyIntId = 0; 


switch (nLogIntId) 
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OAM BindInt (nLogIntId, nPhyIntId); 


{ 

| case XSR_INT_ID_NAND_0O: 

| nPhyIntId = EIrgExt4_7; 
| break; 

default: 

I break; 

oo} 

i} 


SEE ALSO 
PAM _InitInt, PAM EnableInt, PAM _DisableInt, PAM _ClearInt 
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PAM_Enablelint 


DESCRIPTION 
This function enables the specified logical interrupt for NAND device. 
SYNTAX 


VOID 
PAM EnableInt (UINT32 nLogIntId) 


PARAMETERS 


Parameter Type In/Out Description 
nLogIntId UINT32 In Logical interrupt ID number 


RETURN VALUE 
None 
REMARKS 


This function is an optional interrupt function. 
Currently, this function is used for asynchronous operation. 


This function translates the specified logical interrupt ID into the physical interrupt ID and 
enables the interrupt through OS dependent function which enables interrupt. 


EXAMPLE 


| #include <PAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function , 


| #define INT_ID_NAND_O (0) /* Interrupt ID : 1st NAND */ | 


| VOID 

| Example (VOID) 

if 

| PAM_ClearInt ( (UINT32) INT_ID_NAND_0O); 
i PAM_EnableInt ( (UINT32) INT_ID_NAND_0); 
|} 


(2) Example to implement the function in S3C2410 : 


| VOID 

| PAM_EnableInt (UINT32 nLogIntId) 
i { 

; UINT32 nPhyIntId = 0; 


switch (nLogIntId) 
{ 
case XSR_INT_ID_NAND_0O: 
nPhyIntId = EIrqExt4_7; 
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break; 
default: 
| break; 
|} 
OAM_EnableInt (nLogIntId, nPhyIntId); 
i} 
SEE ALSO 


PAM _InitInt, PAM BindInt, PAM _DisableInt, PAM _ClearInt 


XSR v1.5.1 Porting Guide 175 


SAMSUNG DOG Tet! 


aver pee a liwiled 


PAM_Disablelint 


DESCRIPTION 
This function disables the specified logical interrupt for NAND device. 
SYNTAX 


VOID 
PAM DisableInt (UINT32 nLogIntId) 


PARAMETERS 


Parameter Type In/Out Description 
nLogIntId UINT32 In Logical interrupt ID number 


RETURN VALUE 
None 
REMARKS 


This function is an optional interrupt function. 
Currently, this function is used for asynchronous operation. 


This function translates the specified logical interrupt ID into the physical interrupt ID and 
disables the interrupt through OS dependent function which disables interrupt. 


EXAMPLE 


| #include <PAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function , 


| #define INT_ID_NAND_O (0) /* Interrupt ID : 1st NAND */ | 


| VOID 

| Example (VOID) 

if 

i PAM ClearInt ((UINT32) INT_ID_NAND_0); 

i PAM DisableInt ( (UINT32) INT_ID_NAND_0); 
i} 


(2) Example to implement the function in S3C2410 
| VOID i 


| PAM_DisableInt (UINT32 nLogIntId) 
i { 
; UINT32 nPhyIntId = 0; 


switch (nLogIntId) 
{ 
case XSR_INT_ID_NAND_0O: 
nPhyIntId = EIrqExt4_7; 
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break; 
default: 
| break; 
| 3 
OAM DisableInt (nLogIntId, nPhyIntId); 
i} 
SEE ALSO 


PAM _ InitInt, PAM BindInt, PAM _EnableInt, PAM ClearInt 
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PAM_Clearlint 


DESCRIPTION 
This function clears the specified logical interrupt for NAND device. 
SYNTAX 


VOID 
PAM ClearInt (UINT32 nLogIntId) 


PARAMETERS 


Parameter Type In/Out Description 
nLogIntId UINT32 In Logical interrupt ID number 


RETURN VALUE 
None 
REMARKS 


This function is an optional interrupt function. 
Currently, this function is used for asynchronous operation. 


This function translates the specified logical interrupt ID into the physical interrupt ID and 
clears the interrupt through OS dependent function which clears interrupt. 


EXAMPLE 


| #include <PAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function , 


| #define INT_ID_NAND_O (0) /* Interrupt ID : 1st NAND */ | 


| VOID 

| Example (VOID) 

if 

| PAM_ClearInt ( (UINT32) INT_ID_NAND_0O); 
i PAM_EnableInt ( (UINT32) INT_ID_NAND_0); 
|} 


(2) Example to implement the function in S3C2410 : 


_ VOID 

| PAM_ClearInt (UINT32 nLogIntId) 
i { 

; UINT32 nPhyIntId = 0; 


switch (nLogIntId) 
{ 
case XSR_INT_ID_NAND_0O: 
nPhyIntId = EIrqExt4_7; 
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break; 
default: 
| break; 
|} 
OAM_ClearInt (nLogIintId, nPhyIntId); 
i} 
SEE ALSO 


PAM _InitInt, PAM BindInt, PAM _EnableInt, PAM DisableInt 
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PAM_Memcpy 


DESCRIPTION 
This function copies data from the source to the destination. 
SYNTAX 


VOID 
PAM Memcpy (VOID *pDst, VOID *pSrc, UINT32 nlLen) 


PARAMETERS 
Parameter Type In/Out Description 
pDst VOID * Out Array Pointer of destination data to be copied 
pSrce VOID * In Array Pointer of source data to be copied 
nLen UINT32 In Length to be copied 
RETURN VALUE 
None 
REMARKS 


This function is a mandatory memory operation function. 


This function is called by the function that wants to copy data in the source buffer to data in 
the destination buffer. If system can support a functionality for memory copy by hardware, 
PAM Memcpy uses it to adjust the memory copy operation to specific environment of 
platform. If not, PAM_Memcpy just calls OS dependent Memcpy function. 


EXAMPLE 


i #include <PAM.h> 
| #include <XSRTypes.h> 


(1) Example to call the function ; 


_UINT8 SrcBuf [512]; 
| UINT8 DstBuf[512]; 


| VOID 

| Example (VOID) 

1 { 

I PAM Memcpy (&DstBuf[0], &SrcBuf[0], (512)); 


(2) Example to implement the function in S3C2410 
| VOID i 
| PAM_Memcpy (VOID *pDst, VOID *pSrc, UINT32 nLen) 

if 

I OAM_Memcpy (pDst, pSrc, nlbLen); 
i} 
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: VOID 
| PAM_Memcpy (VOID *pDst, VOID *pSrc, UINT32 nLen) 
if 


(3) Example to implement the function in 05912 : 


if (nLen > Oxffff) return; 


DMA_CSSA_L = (unsigned short) ((unsigned int) 

(src) &OxO000FFFF) ; 
DMA_CSSA_U = (unsigned short) (((unsigned int) 

(src) &OxFFFFO0000)>>16); 
DMA_CDSA_L = (unsigned short) ((unsigned int) 

(dst) £OxOOOOFFFF) ; 
DMA_CDSA_U = (unsigned short) (((unsigned int) 

(dst) &OxFFFF0000)>>16); 


DMA_CEN byte_len >> 1; /* channel element number */ 


DMA_CCR 0x54c0; 


/* poll if dma finished */ 
while (! (DMA_CSR&0x8) ) 


{ 
//polling if DMA finished 
} 
return; 
SEE ALSO 


XSR v1.5.1 Porting Guide 181 


SAMSUNG D0GM Tea i! 


aver pee a liviled 


7. Advanced Topics 


This chapter describes Advanced Topics to port XSR: Semaphore, Interrupt, Timer, 
Deferred Check Operation, Byte Alignment Restrictions and ECC Policy. 


7.1. Semaphore 


XSR OAM has 4 semaphore functions. This section describes a role of OAM semaphore 
functions and implementation method of these functions. 


If you use XSR on multi-process or multi-task environment, read follows. 
Otherwise, skip chapter 7.1 and just leave OAM semaphore functions as template. 


7.1.1. Backgrounds 


XSR_ is designed to support multi-process environment partially. In multi-process 
environment, concurrent requests may be issued to XSR. Each layer of XSR has different 
ability to manage this situation. 


STL supports multiple volumes and does not support multiple accesses for one volume. 
STL assumes there is only one request for one volume. That is, STL can not handle 
simultaneous requests for one volume. However for different volumes, STL functions are 
reenterable. Normally this is enough to STL because STL is used by File System, and 
generally File System handles these simultaneous requests for one volume. 


The condition of BML is somewhat different with the condition of STL. 


File Syaher Area 


Figure 7-1. Simultaneous Requests to BML 


There is an example of NAND device volume in Figure 7-1. The example volume has 4 
different areas; boot loader area, Core OS area, OS demand paging area, and File System 
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area. 

There is a demand paging manager which loads proper OS image from NAND device. For 
example, PocketPC2003 kernel supports this style of demand paging. BML is used by both 
STL and demand paging manager concurrently; that means BML receives simultaneous 
requests for same volume. BML is designed to handle these multiple requests for one 
volume by using semaphore. 

If you use multi-task or multi-process environment, there is another situation that BML may 
receive multiple requests for one volume. In that case, you should implement OAM 
semaphore functions. 


Table 7-1. XSR Multiple volume/device supporting 


Supporting STL BML 
Multiple requests for different volumes O O 
Multiple requests for same volume Xx O 
Use semaphore internally Xx O 
Multiple requests for different devices - - 


In conclusion, semaphore is used by BML to handle multiple requests to NAND devices. 
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Figure 7-2. Semaphore Operation in BML 


7.1.2. Semaphore 


Semaphore is traditional I[PC(InterProcess Communication) component used in OS. 
Semaphore is used for two major purposes; shared resources protection and 
synchronization. 

First, semaphore is used to protect shared resources such as memory, device, global variable, 
program code, etc. This protection can include mutual exclusion and critical section concept. 
Second, semaphore is used for synchronization. In second case, semaphore can be used like 
an event or a signal. 


In XSR, semaphore is used by BML, to protect device and BML’s internal data structure 
from multiple requests. 


XSR v1.5.1 Porting Guide 183 


SAMSUNG D0GMT ei! 


averpeie a liviled 


7.1.3. 


When semaphore is used for protection, it is regarded as a key. If one process wants to 
access shared resource, the process should get a key (admission) before starting shared 
resource access. Semaphore has internal counter which is called as a token. Token means 
the number of keys. Semaphore acquiring function is trying to get a key. If semaphore 
token value is bigger than zero, token is decreased and then calling process is returned from 
semaphore acquiring function. If semaphore token value is zero, calling process should wait 
until another process releases semaphore. The process which owns semaphore returns 
semaphore token by semaphore releasing function. 


Most OS have semaphore APIs. These semaphore APIs consist of traditional 4 semaphore 
functions; create, destroy, acquire, and release. 


Figure 7-3. Semaphore Usage Example 


Figure 7-3 shows semaphore usage example. Both Process1 and Process2 want to access 
shared resource. To access shared resource, the process should get semaphore first. In figure, 
Process! first acquires semaphore, and then accesses shared resource. However Process2 
should wait for semaphore released because semaphore is already allocated to Process1. 
After finishing access of shared resource, Process! will release semaphore and then 
Process2 will be able to access shared resource. 


Implementation 
XSR OAM has 4 semaphore functions as follows. 


BOOL32 OAM CreateSM(SM32 *pHandle) 
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BOOL32 OAM DestroySM(SM32 nHandle) 
BOOL32 OAM_AcquireSM(SM32 nHandle) 
BOOL32 OAM _ReleaseSM(SM32 nHandle) 


If you use multi-process environment and multiple requests can be given to BML, you 
should implement OAM semaphore functions. In other words, if you are using NAND 
device volume only for File System or you do not use multi-process environment, then you 
do not need to implement OAM semaphore functions. However, OAM semaphore functions 
should return TRUE32 because BML always calls these functions internally. 


XSR defines a type SM32 for semaphore handle. This type is same with UINT32 (32 bit 
unsigned int type). This handle is set from OAM_CreateSM() and used for other 
semaphore functions to point the created semaphore. 


OAM_CreateSM() Implementation 


OAM_CreateSM() creates semaphore object. 


In current version of XSR, you should remember that BML assumes that created semaphore 
token is zero. Because of this, BML calls OAM_ReleaseSM() just after semaphore 
creating. Therefore, OAM_CreateSM() should create semaphore to have initial zero token 
value. Otherwise, semaphore can not protect NAND device properly. 


OAM _CreateSM() returns TRUE32 or FALSE32. When semaphore is successfully 
created, OAM_CreateSM() should return TRUE32. Otherwise, OAM_CreateSM() 
retums FALSE32. 


(1) OAM_CreateSM() implementation example for pSOS 
BOOL32 

| OAM_CreateSM(SM32 *pHandle) 

i{ 

i BOOL32 bRet = TRUE32; 


if (sm_create("XSRS", 0, SM_LOCAL | SM_FIFO | SM_UNBOUNDED, _ 
(ULONG *)pHandle) != 0) i 
{ 
bRet = FALSE32; 
} 


return bRet; 


(2) OAM_CreateSM() implementation example for WIN32 
| BOOL32 

| OAM_CreateSM(SM32 *pHandle) 

I { 

i HANDLE hSm; 


hSm = CreateSemaphore ( 
(LPSECURITY_ATTRIBUTES) NULL, (LONG) 0, (LONG) 1, 
(LPCTSTR) NULL); 


if ((UINT32) hSm == 0) 
return FALSE32; 
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*pHandle = (SM32) hSm; 


return TRUE32; 


7.1.3.2. OCAM_DestroySM() Implementation 
OAM_DestroySM() destroys semaphore object. 


OAM_ DestroySM () returns TRUE32 or FALSE32. When semaphore is successfully 
destroyed, OAM_DestroySM() should return TRUE32. Otherwise, 
OAM_DestroySM() returns FALSE32. 


(1) OAM_DestroySM() implementation example for pSOS 
| BOOL32 

| OAM_DestroySM(SM32 nHandle) 

if 

i BOOL32 bRet = TRUE32; 


if (sm_delete(nHandle) != 0) 
{ 
bRet = FALSE32; 


} 


return bRet; 


(2) OAM_DestroySM() implementation example for WIN32 

| BOOL32 

| OAM_DestroySM(SM32 nHandle) 

if 

i if (CloseHandle( (HANDLE) nHandle) == TRUE) 
return TRUE32; 


return FALSE32; 


7.1.3.3. OAM_AcquireSM() Implementation 


OAM_AcquireSM() gets semaphore with created semaphore handle. For this acquiring 
process, most OS provide several policies for semaphore waiting. When semaphore token is 
zero, calling process may wait or return error. That wait can be time-outed. 

However, for OAM_AcquireSM() implementation you do not need to care about these 
options. Just implement to wait until semaphore is available. 


OAM AcauireSM() returns TRUE32 or FALSE32. When semaphore is successfully 
acquired, OAM_AcauireSM() should return TRUE32. Otherwise, OAM _DestroySM() 
returns FALSE32. 


(1) OAM_AcquireSM() implementation example for pSOS 


| BOOL32 
' OAM_AcquireSM(SM32 nHandle) 
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| BOOL32 bRet = TRUE32; 

| if (sm_p(nHandle, SM_WAIT, 0) != 0) 
{ 

i bRet = FALSE32; 

return bRet; 

i 


(2) OAM_AcquireSM() implementation example for WIN32 
| BOOL32 

| OAM_AcquireSM (SM32 nHandle) 

lf 

DWORD nRe; 


nRe = WaitForSingleObject ( (HANDLE) nHandle, INFINITE) ; 
if (nRe == WAIT_FAILED) 
return FALSE32; 


return TRUE32; 


7.1.3.4. OCAM_ReleaseSM() Implementation 


OAM_ReleaseSM() releases semaphore with created semaphore handle. 


OAM_ReleaseSM() returns TRUE32 or FALSE32. When semaphore is successfully 


released, OAM_ReleaseSM() should return TRUE32. Otherwise, OAM_ReleaseSM () 
returns FALSE32. 


(1) OAM_ReleaseSM() implementation example for pSOS 
| BOOL32 

| OAM_ReleaseSM(SM32 nHandle) 

| { 

i BOOL32 bRet = TRUE32; 


if (sm_v(nHandle) != 0) 
{ 

bRet = FALSE32; 
} 


return bRet; 


(2) OAM_ReleaseSM() implementation example for WIN32 
| BOOL32 

| OAM_ReleaseSM(SM32 nHandle) 

| { 


if (ReleaseSemaphore ( (HANDLE) nHandle, 1, NULL) == TRUE) 
return TRUE32; 


return FALSE32; 
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7.2. Interrupt 


XSR OAM has 5 interrupt functions. This section describes background of XSR interrupt 
and implementation method of these functions. 


7.2.1. Interrupt of Device Driver Concept 


Device driver operates hardware device such as keyboard, mouse, harddisk, NAND 
memory device, etc. Host processor and hardware device have host - client relationship. In 
this relationship, host processor can send data and command to device easily. But, it is not 
easy to send an event from hardware device to host processor. 


Hoel Devicn 7 iF ; Hardware 


Laver 


Figure 7-4. Device Driver Concept 


Interrupt is a traditional, useful method when hardware sends an event to host. For example, 
when keyboard key is pushed by a user, keyboard controller invokes interrupt to host 
process. 
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Figure 7-5. Interrupt of Hardware Device 


Interrupt is often used to inform that given command is finished by hardware device. 
NAND device provides this type of interrupt. 
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7.2.2. Synchronous / Asynchronous Device Driver Model 


Depending on the interrupt usage, device driver is classified into synchronous and 
asynchronous device driver. 

Synchronous device driver does not use interrupt. After issuing command to hardware 
device, host should wait until the command ends. To know end time, host checks status 
register of hardware device periodically. This periodic checking is called as polling. 


Command 


Processor 


Figure 7-6. Polling 
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Figure 7-7. Synchronous Device Driver Operation 


Polling mode device driver is easy to implement but not efficient because application 
should wait while device is processing the command. Especially in multi-process OS 
environment, synchronous device driver model is not good because there may be another 
process wants to be excuted. 


Asynchronous device driver uses interrupt to avoid useless waiting. Device driver returns 
just after issuing command then application gets CPU control. Hardware device processes 
given command and invokes interrupt to host device driver when given command is over. 
Interrupt service routine of device driver receives CPU control by interrupt, then checks 
error and reports proper result to application. 
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Figure 7-8. Interrupt Usage at Device Driver 
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Figure 7-9. Asynchronous Device Driver Operation 
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Asynchronous model device driver is more efficient than synchronous model driver. 
However, hardware device must have interrupt function and device driver must include 
interrupt functions and interrupt service routine. 


BML and Interrupt 


It takes long time to operate BML_Write(),BML_Erase() and BML_Copyback(). 
Small block NAND’s typical page write time is 200 microsecond(us), and typical block 
erase time is 2 millisecond(ms). Therefore XSR BML provides a method to use 
asynchronous device driver model. You can use BML_FLAG_ASYNC_OP flag on nFlag 
argument of BML functions. If you use BML_FLAG_ASYNC_OP when you are issueing 
BML commands, it is passed to LLD. LLD receives LLD_FLAG_ASYNC_OP option for 
BML’s BML_FLAG_ASYNC_OP. So, if you want to use asynchronous device driver model 
at XSR LLD then you should process properly LLD_FLAG_ASYNC_OP in your LLD. 


However there is a serious problem when you implement asynchronous model LLD. The 
problem is error processing. If LLD receives LLD_FLAG_ASYNC_OP, LLD goes back just 
after issuing NAND command. Because at this time LLD can not know error status, LLD 
can not return proper error code. After that, interrupt service routine can recognize error 
situation but there is no BML API to handle this error for interrupt service routine. To solve 
this problem, you should use Defered Check Operation model. In this model, previous 
operation error is processed at next operation. So interrupt service routine does not need to 
handle NAND error. 


BML_FLAG_ASYNC_OP LLD_FLAG_ASYNC_OP 


BML_WriteQ) XXX_Write() 
NAND Device 
STL and Interrupt 


Figure 7-10. BML and Interrupt 
To support asynshronous mode, STL enable to select asynchronous/synchronous mode 
using bASyncMode flag in STL_Open().STL also supports STL_AWrite() and 
STL_ADelete () functions for asynchronous mode. 
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The mechanism of asynchronous mode of STL is different with the mechanism of 
asynchronous mode of BML. BML functions can be mapped to LLD functions directly in 
no error case. If BML_FLAG_ASYNC_OP flag is selected to use asynchronous driver model 
at BML, the interrupt will be invoked after finishing the given command. However, STL 
functions cannot be mapped to LLD functions directly. STL functions are able to be 
mapped to several BML functions. Because several NAND commands per one STL 
function are issued, the mechanism of asynchronous mode of BML can not be adapted to 
STL. 


Asynchronous feature of STL is different concept with asynchronus API calling of BML. 


7.2.4.1. Asynchronous Feature of STL 
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Figure 7-11. STL to BML Mapping Example 


At frist, STL_AWrite() puts BML operations which are needed to execute STL_AWrite() 
operation into internal operation queue. However, It does not mean that BML functions are 
already called. Actually, a BML function can be called after STL_Sync() is called first. 
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Once STL_Sync() is called, a BML function was dequeueed from head of the operation 
queue, and then can be handled. To minimize the response time of STL, STL_Sync() calls 
only one BML operation at a time. To call BML function in asynchronous mode, STL uses 
BML_FLAG_ASYNC_OP flag as a parameter of BML functions. 


In case of using BML_FLAG_ASYNC_OP flag, the interrupt is occured after the operation 
of the corresponding command is completed. Then, interrupt service routine can call 
STL_Sync() again. 


Once STL_Sync() is called again, STL gets the next BML function and handle it. STL 
repeates BML funtions one by one until the queue becomes empty. In asynchronous mode 


of STL, STL manages one BML function at once to prevent delays in the response time of 
the whole system 


mi : = = 
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Figure 7-12. Operation Queue Created by STL_AWrite() 
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Figure 7-13. STL_Sync() Operation (nQuantum: 1) 


7.2.5. Timer 


7.2.5.1. Asynchronous Feature of XSR and Timer 


As mentioned in previous chapter, STL_AWrite()/STL_ADelete() generates an 
operation queue which has BML job schedules. After creating an operation queue, 
STL_Sync() actually calls one BML operation at a time. Because the major purpose of this 
asynchronous mechanism is to reduce response time of STL, processing time is a key factor 
to STL_Sync(). 


STL_Sync() receives nQuantum which is related to STL response time. 
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Figure 7-14. Flowchart of STL_Sync(Q) 


In current XSR implementation, nOQuantum and timer functions do not mean real timer 
values. The value of nOQuantum means a number of BML operations to be executed at 
once. Timer function returns the value of a global counter variable instead of the timer tick 
of the operating system. The value of counter is related with the number of BML 
operations. 


Actually, OAM_Get Time () returns a current value of a global counter in unsigned int 
type. To understand OAM_GetTime() and OAM _ResetTimer (), you can imagine the 
ordinary counter which increases continuously. OAM_ResetTimer() resets the global 
counter variable as 0, and OAM_Get Time () returns the current value of the counter and 
increases the counter. The return value of the timer function is used for comparing with the 
quantum value of STL_Sync(). 


However, if user wants to implement the asynchronous feature based on execution time of 
operation, timer functions should be changed to use the real OS timer instead of the counter. 
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7.2.5.2. Implementation 
XSR OAM has 2 functions for asynchoronous feature as follows. 


VOID OAM _ResetTimer (VOID) 
UINT32 OAM _GetTime (VOID) 


OAM _ResetTimer () initializes a timer. 


STL_Sync() calls OAM_ResetTimer() before calling OAM_Get Time () . Therefore, 
OAM _ResetTimer() is good function to initialize a timer. If you do not want to use 
STL_AWrite(), STL_ADelete(), and STL_Sync(), you do not need to implement 
this function. 


OAM_Reset Timer () implementation example for Symbian OS 


i static UINT32 nTimerCounter = 0; 
i static UINT16 nTimerPrevCnt = 0; 


| VOID 
| OAM_Reset Timer (VOID) 
| { 


nTimerPrevCnt = 0; 
nTimerCounter = 0; 


OAM _GetTime() returns current timer counter value. 


Because STL_Sync () uses difference of OAM_Get Time () calls for every BML function, 
return timer value’s unit is not important. Just remember this value is compared with 
STL_Sync() argument nQuantum. 


If you do not want to use STL_AWrite(), STL_ADelete(), and STL_Sync(), you 
can implement this function to return constant value. 


OAM_Get Time () implementation example for Symbian OS 
| UINT32 

| OAM_Get Time (VOID) 

| { 


return nTimerCounter+t+; 


7.2.6. Implementation 


7.2.6.1. PAM Implementation 
PAM has 5 interrupt functions as follows. 


VOID PAM InitInt (UINT32 nLogIntId); 
VOID PAM BindInt (UINT32 nLogIntId); 
VOID PAM EnableInt (UINT32 nLogIntId); 
VOID PAM DisableInt (UINT32 nLogIntIdqd); 
VOID PAM ClearInt (UINT32 nLogIntId); 
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These functions are not used inside XSR layer; STL, and BML. These functions may be 
used in LLD or STL’s user layer. 


In current version of XSR, PAM interrupt functions control the interrupts through OAM 
interrupt functions. 


Interrupt handling flow is divided into two: platform dependent part (PAM) and OS 
dependent part (OAM). PAM interrupt functions translate a logical interrupt ID into a 
physical interrupt ID. And PAM interrupt functions call OAM interrupt functions to handle 
the interrupt which is specified by logical interrupt ID and physical interrupt ID. 


Implementation in upper layer of STL 

To use asynchronous feature of XSR, upper layer of STL should have ISR and additional 
function call handler. The ISR recieves interrupts from NAND device and notify it to the 
function call handler. Activated function call handler calls STL_Sync to process 
asynchronous operations. 


If current mode is asynchronous, the upper layer of STL should call PAM_TnitInt and 
PAM _BindInt before calling STL_Init and STL_Open. PAM_InitInt initialize 
interrupts for the NAND device. PAM_BindInt binds interrupts for the NAND device. 
PAM BindInt maps logical interrupts for the NAND device to specific physical 
interrupts. 


In asynchronous mode, STL_AWrite should be called instead of STL_Write. Due to 
limitation of size of the operation queue, maximum size of a write request is restricted in 
asynchronous mode. The size of a write request from upper layer should be smaller than or 
equal to 64 KB. 


After calling STL_AWrite, STL_Sync should be called to handle BML operations in the 
operation queue. Value of nQuantum, a parameter of STL_Sync, should be 1 in current 
version of XSR. 


After dequeueing BML operation from the operation queue, LLD enables the interrupt and 
process the operation. STL_Sync returns STL_SYNC_INCOMPLETE if operations remain 
in the queue. When the NAND device finishes the operation, it generates interrupt to CPU. 
Then ISR lets the function call handler call next STL_Sync. 


If operation queue is empty, STL_Sync returns STL_SYNC_COMPLETE to the function 
call handler and upper layer executes next STL operation. 
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Figure 7-15. Flow between upper layer and XSR in asynchronous mode 


| VOID 
| Example (VOID) 
if 


Example for upper layer of STL to support interrupts : 


if (asynchorouns mode) 


{ 
Calls PAM_InitInt () 


Calls PAM _BindInt () 


Calls STL_Init () 


Calls STL_Open () 


7.2.6.3. Implementation in LLD 
To use the asynchronous feature of XSR, LLD should call PAM_ClearInt() and 
PAM_EnablelInt () at XXX_Write, XXX_Erase, XXX_MErase and 
XXX_CopyBack functions. These functions can receive LLD_FLAG_ASYNC_OP flag. 
When the flag is set, LLD should call PAM_ClearInt() and PAM _EnabletInt () 
before issuing a command to NAND device. 


PAM_ClearInt() clears NAND interrupt. When interrupt service routine is called by 
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7.3.1. 


hardware interrupt, after proper processing of interrupt PAM_ClearInt() should be 
called to avoid endless invoking of the interrupt. 


PAM EnableInt () enables NAND interrupt for next NAND command. Interrupt which 
is handled in LLD should support both interrupt mode command and non-interrupt mode 
command. Because of this, LLD should enable and disable the interrupt. 


Example for LLD Erase to support interrupts ; 
| INT32 i 


| XXX_Erase( .., UINT32 nFlag) 

zi 

i Wait processing command 

Checks previous error and return error code 


if (nFlag & LLD_FLAG_ASYNC_OP) 
{ 


Calls PAM CleartInt () 
Calls PAM _EnablelInt () 
} 


Issues erase command to NAND device 
(do not wait) 


Power-Off Recovery 


XSR OAM has a timer function to handle power-off error in BML layer. This section 
describes background of power-off error processing and implementation method of the 
timer function. 


Power-Off Error Processing and Timer 


BML handles all NAND device errors such as page read error, page write error, block erase 
error, , etc. In case of processing block erase error, there is a problem relate with power-off 
situation. 
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Figure 7-16. Power-off Slope Assumption 


Generally NAND block erase operation consumes more electronic current than NAND page 
write operation. Because of this, power-off slope may cause BML to mistake for block 
erase error handling. Figure 7-16 shows an example of power-off slope. When power is 
offed, the voltage goes down to zero with slope. Because of low voltage, NAND block 
erase and NAND page write operation may fail. If processor’s operating voltage threshold 
is lower than NAND’s threshold, and NAND erase operation is issued at (B) area in Figure 
7-16, BML will try to replace the block. However the block is not real run-time badblock. 
In (B) area, block erase operation is failed but page write function is still working. 
Therefore normal block may be recognized as run-time bad block by BML. 
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Figure 7-17. NAND Block Erase Error at Power-off 


To avoid this wrong run-time bad block processing, BML uses OAM _WaitNMSec(). 
OAM_WaitNMSec() is delay function and receives an argument about delay time. The 
argemnut is given as millisecond unit. 


When BML receives block erase error from LLD, BML calls OAM_WaitNMSec() before 
starting error handling. This delay time can be modified by BML_IOCt1 (). 
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Figure 7-18. OAM_WaitNMSec() Usage 


7.3.2. Implementation 
XSR OAM has | function for power-off recovery as follows. 


VOID OAM WaitNMSec (UINT32 nNMSec) ; 
OAM_WaitNMSec () delays during given milliseconds. 


If you do not care about power-off case, you do not need to implement 
OAM_WaitNMSec(). 


OAM_Get Time () implementation example for Win32 
/ VOID 

| OAM_WaitNMSec (UINT32 nNMSec) 

| { 

| Sleep (nNMSec) ; 

i} 
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7.4. Deferred Check Operation 


Deferred Check Operation is an algorithm to change the operation sequence of the general 
operation in software. It efficiently uses time for Physical Operation of the device; that 
improves the system performance. A user can adapt Deferred Check Operation in write 
operation and erase operation function. 


The sequence of the general operation of the device is divided into three; 
@ Pre-Operation before Command Issue 
(Register Setting + Data Transfer) 
@ Physical Operation the real operation is executed 
@ Normal operation Check 


The following figure compares the general operation with Deferred Check Operation. 


General Operation 
Oaia Transfer Upper layee Uppes Layer 
* Physical mperaben operation 


Aegisier Seping Operation 


a - = 


Function Command issue Fancilom ond Command issue Functlon end 
Sari 


Deferred Check Operation 


Previous Time Save 
Operatian Check 


ii ‘Ceara nial eat 
ini * Fancilow End 


Command sue 
* Fiction End 


Figure 7-19. Compare General Operation with Deferred Check Operation 


The sequence that the general operation is executed is as follows; 


@ Register related to the operation is set. 
Data of the host memory is transferred to the buffer of the device 
(in write operation), 

@ Physical Operation is executed in the buffer of the device to NAND array cell 
(in write/erase operation), 

@ Finally, check the operation is normally executed. 


Here, step @ is the time for Physical Operation. CPU suspends as idle during Physical 
operation. 


Deferred Check Operation is designed to efficiently use CPU idle time. Using Deferred 
Check Operation, the corresponding function is closed after issuing the command. LLD can 
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execute other operation during time for Physical Operation. Thus, the total system 
performance is improved. 


As the function of Deferred Check Operation closes its operation without handling after 
step @, Operation Check (step @) is deferred to the middle of the sequence of next 
Operation (step @). A user implement that step @ (checking the former operation is 
normally executed) in the middle of all Operation functions. 

After issuing the command, LLD handles the corresponding function. CPU does not wait as 
idle during Physical Operation time about the device. Else, CPU executes the next operation. 
Thus, the overall system performance is improved using Deferred Check Operation. 


The sequence that Deferred Check Operation is executed is (The sequence depends on the 
device) as follows; 


1. Data Transfer or Register Setting (D) 

2. Host checks the former operation is normally executed (@) 

3. If no error, LLD issues the command (Command Issue) (@) 

4. LLD finishes the corresponding function of the new command 

5. While the device executes Physical Operation, CPU can execute the next operation. 


(@) 


If a user wants to use Deferred Check Operation, LLD has the process to handle the 
previous operation error. When the previous write operation error occurs in LLD, BML has 
to handle this error. In this case, BML requests data used in the previous write operation. 
XXX_GetPrevOpData is used for data request of BML. 

If a user does not use LLD, a user does not it need to implement XXX_GetPRevOpData 
in LLD functions. (However, XXX_GetPrevOpData itself must be existed because of 
LFT policy of BML.) 


Deferred Check Operation functions are as follow; 


- XXX_GetPrevOpData 
- XXX_Flushop 
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7.5. Byte Alignment Restrictions 


Most of CPUs require that objects and variables reside at particular location in the system 
memory. For example, 32 bit microprocessors typically organize the memory as shown 
below. The memory is accessed by performing 32 bit bus cycles. 32 bit bus cycles can be 
performed at the addresses that are divisible by 4. This requirement is called "byte 
alignment". Thus, a 4byte integer can be located at 0x1000 or 0x1004, but cannot be located 
at Ox1001. 


To handle the misaligned interger for the read/write operation costs more than to handle the 
aligned interger for the read/write operation. 

For example, an aligned 4byte integer X would be written as XO, X1, X2 and X3. Thus the 
microprocessor can read the complete 4byte integer in a single bus cycle. However, if the 
same microprocessor attempts to access 4byte integer at address OxOO0OD, it will have to 
read bytes YO, Y1, Y2 and Y3. This read cannot be performed by a single 32 bit bus cycle. 
The microprocessor has to perform twice different read operations at address 0x100C and 
0x1010 to read the complete 4byte integer Thus it takes twice time to read the misaligned 
Abyte integer than to read the aligned 4byte integer. . 


Table 7-2. 4Byte Alignment Example 


Byte 0 Byte 1 Byte 2 Byte 3 
0x1000 
0x1004 X0 Xl X2 x3 
0x1008 
0x100C YO Y1 Y2 
0x1010 


Thus, users must handle the “byte alignment” problem when writing LLD codes. 


For example, let suppose to use NAND device that accesses bus Bandwidth. If the buffer 
address is an odd number in read/write operation, the “byte alignment” problem occurs. To 
solve this byte alignment problem, LDD fixes 2byte alignment using the aligned buffer. 


Also, if a device access data using assembler, a user has to set as 4Byte alignment not to 
broke the buffer. 


The following is an example code of 4Byte alignment in reading data using assembler. 


| INT32 PNS_Read(UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, 
: UINT8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag) 


UINT32 nBAddr; 
PNSSpec *pstDevSpec; 
UINT8 n4Cycles; 
UINT8 *pTmpMBuf; 
UINT8 *pTmpSBuf; 


PNS_DBG_PRINT((TEXT("[PNS : IN] ++PNS_Read() nPsn 
sd\r\n"), nPsn)); 


pstDevSpec = astPNSDev[nDev] .pstDevSpec; 
nBAddr = DEV_BASE (nDev) ; 
n4Cycles = pstDevSpec—>n4CycleDev; 
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pImpMBuf 
pImpsBuf 


pMBuf; 
pSBuf; 


/* if pMBuf is not aligned by 4 bytes, */ 
if ((UINT32) pMBuf & 0x03) 
{ 
pImpMBuf = (UINTS8 *) astBufBA[nDev] .pBAMBuf; 


/* if pSBuf is not aligned by 4 bytes, */ 
if ((UINT32) pSBuf & 0x03) 


pImpSBuf = (UINT8 *) astBufBA[nDev] .pBASBuf; 


if (pTmpMBuf != NULL) 


NF_CMD (nBAddr, CMD_READ) ; 
SET_ADDR(nBAddr, nPsn, n4Cycles); 
NF_WAITRB (nBAddr) ; 
NF_CMD (nBAddr, CMD_READ) ; 

/* It is Implemented to Assembler Code */ 
pstDevSpec—>Read512 (pTmpMBuf, rNFDATAPtr (nBAddr) ); 


if (pTmpSBuf != NULL) 
{ 
pstDevSpec—>Read16(pTmpSBuf, rNFDATAPtr (nBAddr) ) ; 


NF_CMD (nBAddr, CMD_READ_SPARE) ; 

SET_ADDR(nBAddr, nPsn, n4Cycles); 

NF_WAITRB (nBAddr) ; 

NF_CMD (nBAddr, CMD_READ_SPARE) ; 


pstDevSpec-—>Read16(pTmpSBuf, rNFDATAPtr (nBAddr) ); 
/* if pMBuf is not aligned by 4 bytes */ 
if ((UINT32) pMBuf & 0x03) 
PAM Memcpy (pMBuf, pTmpMBuf, PNS_MAIN_SIZE); 
/* if pSBuf is not aligned by 4 bytes */ 
if ((UINT32) pSBuf & 0x03) 


PAM Memcpy (pSBuf, pTmpSBuf, PNS_SPARE_SIZE) ; 


PNS_DBG_PRINT((TEXT("[PNS : OUT] --PNS_Read()\r\n"))); 


return (PNS_SUCCESS) ; 


static VOID 
_Read512x16(UINT8 *pBuf, UINT32 nAddr) 


asm ("mov r0O, 30" : : "g" ((UINT32) pBuf)); 
asm ("mov rl, 30" : : "g" ((UINT32) nAddr)); 
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asm("stmfd 


sp!y {rl = ril}"); 


asm ("mov r2, #0x200"); 
asm("asmr512x16:"); 

asm("ldrh r4, pan I ad Be 

asm("ldrh £3, [rlye")¢ 

asm("orr r4, r4, v3, 1sl #16"); 
asm("ldrh ro, [rl] ™) 4 

asm("ldrh r3, [rl]™); 

asm("orr r5, 15; 13, Isl. #16"); 
asm("ldrh r6,- freij™)s 

asm("ldrh 3, [rl]™)? 

asm("orr r6, r6, v3, 1sl #16"); 
asm("ldrh rly ely")? 

asm("ldrh r3, [rl] ™) > 

asm("orr r7, ri; £3; Isl. #16"); 
asm("ldrh ES; fri") 

asm("ldrh r3, frij"); 

asm("orr r8, r8, r3, 1sl #16"); 
asm("ldrh £9, [rl] ™)4 

asm("ldrh ©r3, [rl]™); 

asm("orr r9, r9, v3, 1sl #16"); 
asm("ldrh ric, [rij*)s 
asm("ldrh £3; [rl]")? 

asm("orr r10, r10, r3, 1sl #16"); 
asm("ldrh rid, [Teli 
asm("ldrh P37. [rly 

asm("orr rll, rid, 73, 1sl #16"): 
asm("stmia r0O!, {r4 -— rl11}"); 
asm("sSubs r2, r2, #32"); 


asm("bne 


i asm("ldmfd 
i 


' static VOID 


| _Read16x16(UINT8 *pBuf, 


i 
i asm ("mov 
asm ("mov 


asm("stmfd 
asm("ldrh 
asm("ldrh 
asm("orr 
asm("ldrh 
asm("ldrh 


asm("orr 


asm("ldrh 


asmr512x16"); 
spl, {rl = rli}™); 
UINT32 nAddr) 


20" 


20" 


r0, 
ri, 


((UINT32) pBuf)); 
((UINT32) nAddr)); 


"g™ 
Mire al 
sp!,{rl. = r7}")3 
[rl 
rl 
r4, 


"); 
"); 
r3, 1lsl #16"); 
[rl] 
rl 
65: 


")i 
")i 


r3, 1sl #16"); 


r1]"); 
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asm("ldrh es, [eLI™¢ 
asm("orr r6, r6, £3, 1sl #16"); 


asm("ldrh el, [elim is 
asm("ldrh £3, [rlj]™)3 
asm("orr r7, ri, £3, 1sl #16"); 


asm("Stmia rO!, {r4 - r7}"); 


asm("ldmfd sp!, {rl - r7}"); 


7.6. ECC Policy 


XSR is designed to support both software ECC and hardware ECC. Software ECC codes 
are included in BML Layer and Hardware ECC should be implemented in LLD Layer. 


Therefore, user should set nEccPol corresponding to ECC policy that users use as follows; 


1. When the value of nEccPol should set as SW_ECC 

If user wants to use software ECC which is supported by XSR, sets the value of nEccPol 
flag as SW_ECC. In that case, BML handles ECC generation and correction by Hamming 
code. 


2. When the value of nEccPo1 should set as HW_ECC 

If user wants to use hardware ECC which is supported by hardware, sets the value of 
nECCPol as HW_ECC. In that case, hardware ECC should satisfy following conditions. 
First, ECC algorithm supported by hardware should be identical with ECC algorithm used 
by Samsung’. Second, spare assignment for generated ECC code by hardware should be 
idendtical with NAND Flash Spare Area Assignment Standard of Samsung *. Third, 
stored ECC pattern should be compatible with SAMSUNG standard. If hardware ECC to be 
used can not satisfy these conditions, user sets the value of nEccPol as NO_ECC instead 
of HW_ECC. 


3. When the value of nEccPo1 should set as NO_ECC 

When user does not use any ECC algorithm, the value of nEccPol sets as NO_ECC. If 
hardware ECC algorithm is different from ECC algorithm used by Samsung, stored ECC 
pattern is not compatible with SAMSUNG standard or spare assignment for ECC code is 
identical with Samsung standard, the value of nECCPo1 should also be set as NO_ECC. If 
spare assignment for ECC code is different from Samsung standard although hardware ECC 
algorithm and ECC pattern are identical with ECC algorithm used by Samsung, XSR can 
not be used in this case. To use XSR, users must obey spare assignment standard of 
Samsung. 


7 Memory Division, Samsung Electronics Co., Ltd, “ECC(Error Checking & Correction) Algorithm”, 
http://www.samsung.com/Products/Semiconductor/Flash/TechnicalInfo/eccalgo_040624.pdf 


’ Memory Division, Samsung Electronics Co., Ltd,” NAND Flash Spare Area Assignment Standard”, 
http://www.samsung.com/Products/Semiconductor/Flash/Technicallnfo/Spare_assignment_recommendation.pd 


f 
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General usages of Hardware ECC are as follows; 


1. Hardware ECC by NAND Device (for example, OneNAND) 
2. Hardware ECC by CPU (for example, NAND controller) 


The implementation and attention of the above cases are as follows. 


XO Implementation 


Method of read/write operation for main area and spare area in LLD are exaplained in 
following table. 


Table 7-3. Usage of Main Buffer and Spare Buffer in Read/Write Operation 


Main Buffer Spare Buffer 
Page Read/Write Should be allocated Should be allocated 
Main Read/Write Should be allocated NULL 
Spare Read/Write NULL Should be allocated 


When performing page read/write operation with ECC ON in the system where Hardware 
ECC is integrated or CPU handles ECC, work flow is like below 


In Read operation: 
1. Read main and spare area 
2. Generate ECC Code 
3. Compare generated ECC with Original ECC which read from spare area. 
4. If 1bit ECC error occurs then return a LLD_ READ CERROR XX. 
or 2bit ECC error occurs then return a LLD_ READ UERROR_XX. 


In Write operation: 
1. Generate ECC Code 
2. Write main and spare area 


In case of OneNAND device, it can get generated ECC values by using register of device. If 
CPU supports Hardware ECC, codes should be implemented to get ECC value generated by 
CPU, corresponding to the above sequence. 


O Attention that spare buffer is NULL in read/wrie main area 


When reading and writing only main area as ECC ON, reading and writing ECC value 
causes problems because spare buffer is null. In order to solve this problem, follow the 
below sequences 


In Read operation, 


1. Allocate spare buffer in LLD layer 

2. Read main/spare area 

3. Generate ECC value for main area 

4. Compare genetated ECC with ECC for main area in spare area 

5, If 1bit ECC error occurs then return a LLD_ READ CERROR XX. 
or 2bit ECC error occurs then return a LLD_ READ UERROR_XX. 
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In Write operation, 


1. Allocate spare buffer and fill as OxFF in LLD layer 

2. Fill main buffer with data 

3. Generate ECC value for main area 

A. Fill generated ECC in ECC position of allocated spare buffer. For more 
information about ECC position, refer to "Spare assignment Standard".’ 

5. Write main and spare area 


The following tables are return values when ECC error occur. 


Table 7-4. Return values of Main area ECC error 


Correctable error 


Uncorrectable error 


1“ Sector of a page 


LLD 


READ_CERROR_MO 


LLD_READ_UERROR_MO 


2" Sector of a page 


LLD 


READ_CERROR_M1 


LLD_READ_UERROR_M1 


3" Sector of a page 


LLD 


READ_CERROR_M2 


LLD_READ_UERROR_M2 


4" Sector of a page 


LLD 


READ_CERROR_M3 


LLD_READ_UERROR_M3 


Table 7-5. Return values of Spare area ECC error 


Correctable error 


Uncorrectable error 


1* Sector of a page 


LLD 


READ_CERROR_SO 


LLD_READ_UERROR_SO 


2" Sector of a page 


LLD 


READ_CERROR_S1 


LLD_READ_UERROR_S1 


3" Sector of a page 


LLD 


READ_CERROR_S2 


LLD_READ_UERROR_S2 


4" Sector of a page 


LLD 


READ_CERROR_S3 


LLD_READ_UERROR_S3 


Return value is divided into the major value and minor value. 


Major value classifies errors of an operation. 
Minor value represents details of errors. 


For example, If user read a page of large block NAND. When uncorrectable ECC error 
occurs at first and third sectors, LLD_READ_UERROR_XX has minor return values. It can 


be described as the following formula after combining with LLD_READ_ERROR. 


nRet = LLD_READ_ERROR | LLD_READ_UERROR_SO | LLD_READ_UERROR_S2; 


The following is an example of LLD Read/Write Function using hardware ECC of 


CPU(NAND Controller). This example adapts small block NAND device. 


| INT32 


i; PNS_Read (UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, 


UINT8 *pMBuf, 


UINTS8 *pSBuf, 


UINT32 nFlag) 


° Memory Division, Samsung Electronics Co., Ltd, *"NAND Flash Spare Assignment recommendation’, 


http://www.samsung.com/Products/Semiconductor/Flash/TechnicalInfo/Spare_assignment_recommendation.pd 
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UINT32 nBAddr; 

INT32 nRet = PNS_SUCCESS; 
UINT8 aEccVal[5]; 

UINT8 aEccValNew[5]; 
UINT8 *pEccM; 

UINT8 *pEccS; 

UINT8 *pEccMNew; 

UINT8 *pEccSNew; 

UINTS *pS; 

UINT8 aSBuf [LLD_SPARE_SIZE]; 
INT32 nERet; 

PNSSpec *pstDevSpec; 

UINT8 n4Cycles; 


PNS_LOG_PRINT((TEXT("[PNS: IN] ++PNS_Read() nPsn = %d\r\n"), 
nPsn)); 


pstDevSpec = astPNSDev[nDev] .pstDevSpec; 
nBAddr = astPNSDev[nDev] .BaseAddr; 
n4Cycles = pstDevSpec-—>n4CycleDev; 


if (nFlag & LLD_FLAG_ECC_ON) 
{ 


pS = pSBuf; 


if( pSBuf == NULL) 
{ 
pS = aSBuf; 
} 
pEccM = &aEccVal [0]; 
pEccS = &aEccVal [3]; 


pEccMNew = &aEccValNew[0]; 
pEccSNew = &aEccValNew[3]; 


if (pMBuf != NULL) 
NF_CMD (nBAddr, CMD_READ); 
SET_ADDR(nBAddr, nPsn, n4Cycles); 
NF_WAITRB (nBAddr) ; 
NF_CMD (nBAddr, CMD_READ) ; 


if (nFlag & LLD_FLAG_ECC_ON) 
{ 

PAM_ECCRgReset () ; 
} 


Read512Bx8 (pMBuf, rNFDATAPtr (nBAddr) ); 


if (nFlag & LLD_FLAG_ECC_ON) 
{ 
PAM_GenEccM (pEccMNew) ; 
Read16Bx8 (pS, rNFDATAPtr (nBAddr) ); 
} 
else 
{ 
if (pSBuf != NULL) 
: 
Read16Bx8 (pSBuf, rNFDATAPtr (nBAddr) ) ; | 
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else 
{ 


CMD_READ_SPARE) ; 


NF_CMD (nBAddr, 
nPsn, n4Cycles); 


SET_ADDR (nBAddr, 


NF_WAITRB (nBAddr) ; 
NF_CMD (nBAddr, CMD_READ SPARE); 


if (nFlag & LLD_FLAG_ECC_ON) 
{ 
Read16Bx8 (pS, 


else 
Read16Bx8 (pSBuf, 


} 
if (nFlag & LLD_FLAG_ECC_ON) 


{ 
PAM Memcpy (aEccVal, 
sizeof (aEccVal) ); 


if (pMBuf != NULL) 
{ 
((pEccM[0] 
(pEccM[1] 


(pEccM [2] 


!= pEccMNew[1] 
!= pEccMNew[2] 


age 


!= pEccMNew [0] ) 
) 
)) 


xrNFDATAPtr (nBAddr) ) ; 


} 
rNFDATAPtr (nBAddr) ) ; 


(UINT8*) (pS + _GetECCPos(nDev)), 


ECCMNew, 


{ 
nERet = 


PAM_CompEccM(pEccM, p 
(UINT8*) (pMBuf) ) ; 


ERROR) 


SWECC_C_ 


if (nERet 


nRet |= 


} 
else if (nE 


} 
!= NULL) 


if (pSBuf 


if ((pEccS[0] 
(pEccS [1] 


{ 
nERet = 


{ 
PNS_LOG_PRINT ( (TEXT ("[PNS:MSG] 
at Main of Psn %$d\r\n"), 


1lbit ECC Err 
nPsn)) ; 


(PNS_READ_ERROR | 
(PNS_READ_CERROR_MO) ) ; 


ERROR) 


ECC_U_! 


{ 
PNS_ERR_PRINT ( (TEXT ("[PNS:ERR] 


{ 
PAM_GenEccS (pEccSNew, 


!= pEccSNew[0]) 
!'= pEccSNew[1]) ) 


2bit ECC Err 
at Main of Psn %d in PNS_Read 
nPsn, nDev)); 


nDev %d\r\n"), 


(PNS_READ_ERROR | 
(PNS_READ_UERROR_MO) ) ; 


(UINT8*) (pS + 
_GetLsnPos (nDev))); 


pEccSNew, (UINT8*) (pS 


PAM_CompEccS (pEccS, 
+ _GetLsnPos (nDev))); 
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PNS_LOG_PRINT ((TEXT("[PNS:MSG] EccSNEW : 0x%x 

x\r\n"),*pEccSNew, *pEccS) ); 

PNS_LOG_PRINT((TEXT("[PNS:MSG] EccSNEW : Ox%x 
EccS : 0x%x\r\n"),* (pEccSNew+1), 
* (pEccS+1))); 

if (nERet == SWECC_C_ERROR) 

{ 


PNS_LOG_PRINT((TEXT("[PNS:MSG] lbit ECC Err 

at Spare of Psn %d\r\n"), nPsn)); 
nRet = (PNS_READ_ERROR | 

(PNS_READ_CERROR_SO)); 


} 
else if (nERet == SWECC_U_ERROR) 
{ 

PNS_ERR_PRINT((TEXT("[PNS:ERR] 2bit ECC Err 
at Spare of Psn %d in FIL_Read 
nDev %d\r\n"), nPsn, nDev)); 

nRet = (PNS_READ_ERROR | 
(PNS_READ_UERROR_SO) ); 


PNS_LOG_PRINT ( (TEXT ("[PNS:OUT] --PNS_Read()\r\n"))); 


return nRet; 


INT32 
PNS_Write(UINT32 nDev, UINT32 nPsn, UINT32 nNumOfScts, 
UINTS8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag) 

{ 

UINT8 aEccVal [5]; 

UINT8 *pEccM, *pEccs; 

UINT8 nEccPos; 

UINT8 aSBuf [LLD_SPARE_SIZE]; 

UINT8 *pS; 

UINT8 nData; 

UINT32 nBAddr; 

INT32 nRet = PNS_SUCCESS; 


PNS_LOG_PRINT((TEXT("[PNS: IN] ++PNS_Write() nPsn = %d\r\n"), 
nPsn)); 


nBAddr = _DevBase (nDev) ; 

if (nFlag & LLD_FLAG_ECC_ON) 
PAM_ECCRgReset () ; 

if ((pMBuf == NULL) && (pSBuf == NULL) ) 


return (PNS_ILLEGAL ACCESS) ; 


if (nFlag & LLD_FLAG_ECC_ON) 


PNS_LOG_PRINT((TEXT("[PNS:MSG] ECC_ON\r\n"))); 
pS = pSBuf; 
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} 


if (pSBuf == NULL) 

{ 
OAM _Memset (aSBuf, OxFF, LLD_SPARE_SIZE) ; 
pS = aSBuf; 

} 


OAM _Memset (aEccVal, OxFF, sizeof (aEccVal)); 


pEccM = &aEccVal [0]; 

pEccS = &aEccVal [3]; 

nEccPos = (UINTS8) (_GetECCPos (nDev) ); 
if (pSBuf != NULL) 


{ 
PAM_GenEccS (pEccS, pS + _GetLsnPos (nDev) ); 
} 


(pMBuf != NULL) 


NF_CMD (nBAddr, CMD READ); 
NF_CMD (nBAddr, CMD WRITE); 


_SetAddr(nDev, nPsn, 0); 
Write512Bx8 (pMBuf, rNFDATAPtr (nBAddr) ) ; 


if (nFlag & LLD_FLAG_ECC_ON) 
{ 
PAM_GenEccM (pEcc™M) ; 
PAM Memcpy ((UINT8*) (pS + nEccPos), aEccVal, 
sizeof (aEccVal) ); 


Writel6Bx8 (pS, xrNFDATAPtr (nBAddr) ); 
} 
else 
{ 
if (pSBuf != NULL) 
{ 
Writel6Bx8 (pSBuf, rNFDATAPtr (nBAddr) ); 
} 
} 


else 


{ 


if (nFlag & LLD_FLAG_ECC_ON) 
{ 
PAM Memcpy ((UINT8*) (pS + nEccPos), aEccVal, 
sizeof (aEccVal) ); 
} 
NF_CMD (nBAddr, CMD_READ_SPARE) ; 
NF_CMD (nBAddr, CMD_WRITE) ; 


_SetAddr(nDev, nPsn, 0); 


if (nFlag & LLD_FLAG_ECC_ON) 
{ 
Writel6Bx8 (pS, xrNFDATAPtr (nBAddr) ); 
} 
else 
{ 
Writel6Bx8 (pSBuf, rNFDATAPtr (nBAddr) ); 
} 
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} 
NF_CMD (nBAddr, CMD _WRITE_CONFIRM) ; 


NF_WAITRB (nBAddr) ; 
NF_CMD (nBAddr, CMD_READ_STATUS); 


nData = NF_RDDATA (nBAddr) ; 


if ((nData & 0x01) != (UINT8) 0x00) 


{ 
PNS_ERR_PRINT ((TEXT("[PNS:ERR] Write 
Err (nPsn:%d)\r\n"), nPsn)); 
PNS_LOG_PRINT ( (TEXT ("[PNS:OUT] --PNS_Write()\r\n"))); 
nRet = PNS_WRITE_ERROR; 
} 


PNS_LOG_PRINT ((TEXT("[PNS:OUT] --PNS_Write()\r\n"))); 


return (nRet); 
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Appendix 


Appendix contains the header file of each module (OAM, LLD and PAM), so a user can 


refer them in porting. 


OAM.h 


#ifndef _XSR_OAM H_ 
#define _XSR_OAM H_ 


/* OS Selection 
/* WINCE_OAM : the definition for WindowsCE 


/* SYMOS_OAM : the definition for SymbianOS 
/* 


#if£ defined (WINCE_OAM) 
#include <windows.h> 
#define XSR_RTL_PRINT (x) RETAILMSG(1, x) 
#if defined (OAM_DBGMSG_ENABLE) 


#define XSR_DBG_PRINT (x) RETAILMSG(1, x) 
#tendif /* OAM_DBGMSG_ENABLE */ 


#elif defined (SYMOS_OAM) 


#if defined (SYMOS_OAM EKA2) 
#include <locmedia.h> 
#include <platform.h> 

f#endif 

#if defined(SYMOS_OAM _EKA1) 
#include <k32std.h> 
#ifdef REAL TARGET 
#include <m32std.h> 
#endif 

fendif 


#define XSR_RTL_PRINT (x) Kern::Printf x 
#if defined (OAM_DBGMSG_ENABLE) 

#if defined (SYMOS_OAM_EKA2) 

#define XSR_DBG_PRINT (x) Kern::Printf x 


f#endif 


#if defined (SYMOS_OAM_EKA1) 


#endif 
#endif /* OAM_DBGMSG_ENABLE */ 


#if defined(SYMOS_OAM _EKA2) 
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a 
*f 
*/ 
a A 
be 


[%ORK KK KK KIKI I I / 


#define XSR_DBG_PRINT (x) __KTRACE_OPT(KBOOT, Kern::Printf x) 
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#define TEXT (x) 
f#endif 
#if defined (SYMOS_OAM _EKA1) 

#define TEXT (x) 
f#endif 


#else /* other case */ 


#define XSR_RTL_PRINT (x) 
#else 
#define XSR_RTL_PRINT (x) 


#if defined (OAM_DBGMSG_| 


#if defined (OAM_RTLMSG_DISABLE 


(x) 


_L (x) 


—_ 


OAM Debug x 


#endif /* OAM_RTLMSG_DISABLE */ 


ENABLE) 


#define XSR_DBG_PRINT (x) 
#else 
#define XSR_DBG_PRINT (x) 


#undef TEXT 
#define TEXT (x) 


fendif 


/* NULL #defines 


#ifndef NULL 

#ifdef __ cplusplus 
#define NULL 

#else 

#define NULL 

#endif 

#endif 


#ifdef __ cplusplus 
extern "C" { 
#endif /* __cplusplus */ 


#ifdef ASYNC_MODE 


OAM Debug x 


#endif /* OAM_DBGMSG_ENABLE */ 


(VOID *) (x) 


[KK KK KK KK IKK IK I I I I IR I I I KI I I I I OK / 


aes 


/* If Each OAM header file defines NULL, following define is not used.*/ | 
[ORK KK HK KK KK I I A I A A H 


((void *)0) 


[RK KK KK KK KK I I I I A I I I I / 


/* exported function prototype of OAM */ 
[KK KK KK KK IKK KK IK I I I I I I I I I I A I I I I A I / 


VOID OAM_InitInt (UINT32 nLogIntId); 

VOID OAM_BindInt (UINT32 nLogIntId, UINT32 nPhyIntId); 
VOID OAM_EnableInt (UINT32 nLogIntId, UINT32 nPhyIntId); 
VOID OAM_DisableInt (UINT32 nLogIntId, UINT32 nPhyIntIdqd); 
VOID OAM_ClearInt (UINT32 nLogIntId, UINT32 nPhyIntId); 
#endif 

VOID *OAM Malloc (UINT32 nSize); 

VOID OAM Free (VOID *pMem) ; 

VOID OAM_Memcpy (VOID *pDst, VOID *pSrc, UINT32 nLen); 
VOID OAM _Memset (VOID *pDst, UINT8 nData, UINT32 nlLen); 
INT32 OAM_Memcmp (VOID *pCmp1,VOID *pCmp2, UINT32 nLen); 
BOOL32 OAM_CreateSM (SM32 *pHandle); 

BOOL32 OAM_DestroySM (SM32 nHandle); 

BOOL32 OAM_AcquireSM (SM32 nHandle); 
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i BOOL32 OAM _ReleaseSM (SM32 nHandle); 

; UINT32  OAM_Pa2Va (UINT32 nPAddr) ; 

| VOID OAM_Debug (VOID *pStr; «s«); 
| VOID OAM _ResetTimer (VOID); 

; UINT32 OAM_GetTime (VOID) ; 

: VOID OAM _WaitNMSec (UINT32 nNMSec) ; 

| BOOL32 OAM_GetROLockFlag (VOID); 

? VOID OAM_Idle (VOID) ; 


| #ifdet __cplusplus 
i} 
i #endif /* __cplusplus */ 


i #endif /* _XSR_OAM_H_ */ 


ll. LLD.h 


| #ifndef _XSR_LLD_H_ 
; #define _XSR_LLD_H_ 


FICCI / 


: /* Debug Configurations tof 
FOO IO IO II II II IOI III II III II IO II I IO I IO I II a IO / 
| #define LLD RTL PRINT (x) XSR_RTL_PRINT (x) 


| #i£ defined (LLD_DEBUG) 

| #define LLD_DBG_PRINT (x) XSR_DBG_PRINT (x) 
i #felse 
| #define LLD_DBG_PRINT (x) 
i #endif /* LLD_DEBUG */ 


FOO IO I IO II III II II II III III II I IO IO I IO I IO I I IO A I / 


i /* External Constant Definitions */ 
FIO III ICICI ICICI ICICI III IOI I ICI IO IIA A kk / 
i #define LLD_MAIN_SIZE 512 

| #define LLD_SPARE_SIZE 16 

| #define LLD_SECTOR_SIZE (LLD_MAIN_SIZE) 

| #define LLD_BW_x08 0 

| #define LLD_BW_X16 1 

: #define LLD_BW_x32 2 

| #define LLD_ME_NO 0 

| #define LLD_ME_OK 1 

| #define LLD_MEBL_LEN 16 


FOO IO IOC IO II II III III II II IO III IO IO I IO I IO I I IO A I / 


: /* LLD Return Values */ 
BKK RR RK KK RK RRR KKK RRR KKK KR RK RK RK KK KR RK KK / 
| /*-------------------- */ 
: /* Major Return Value */ 


|< */ 
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| #define 
| #define 
| #define 
| #define 
| #define 
| #define 
; #define 
| #define 
| #define 
| #define 
| #define 
| #define 
| #define 
| #define 
| #define 
| #define 
| #define 
: #define 


| #define 


LLD_READ_DISTURBANCE 


LLD_IOC_NOT_SUPPORT 


i1LD_DEV_NOT_OPENED 


LLD_DEV_POWER_OFF 


LLD_DEV_NO_LLD_FUNC 
LLD_INIT_BADBLOCK 
iLD_INIT_GOODBLOCK 
LLD_SUCCESS 


LLD_ERASE_ERROR 


LLD_MERASE_ERROR 


LLD_WRITE_ERROR 


LLD_READ _ 


ERROR 


iLD_CRITICAL_ERROR 
LLD_WR_PROTECT_ERROR 
iLD_ILLEGAL_ACCESS 


LLD_ALREADY_INITIALIZED 


LLD_INIT_FATILURE 
i1LD_OPEN_FATLURE 
LLD_CLOSE_FATILURE 


m7 


i: /* Minor Retun Value */ 


ze 


ia 


XSR_RETURN_VALUE (0, 0x0007, 0x0000) 
/* 1-Bit error by read disturbance */ | 
XSR_RETURN_VALUE (0, 0x0006, 0x0000) : 


/* Not supported IO Ctrl 


XSR_RETURN_VALUE (0, 0x0005, 0x0000) 


/* Device not opened 


XSR_RETURN_VALUE (0, 0x0004, 0x0000) 


/* Power is not 


/* success 


XSR_RETURN_VALUE (1, 0x0001, 


/* erase error 


XSR_RETURN_VALUE (1, 0x0002, 


/* merase error 


XSR_RETURN_VALUE (1, 0x0003, 


/* write error 
XSR_RETURN_VALUE (1, 
/* read error 


XSR_RETURN_VALUE (1, 0x0008, 
XSR_RETURN_VALUE (1, 0x0009, 
XSR_RETURN_VALUE (1, 0x000A, 


0x0000, 


0x0005, 


supported to LLD */ | 
XSR_RETURN_VALUE (0, 0x0003, | 
XSR_RETURN_VALUE (0, 0x0002, 
XSR_RETURN_VALUE (0, 0x0001, 
XSR_RETURN_VALUE (0, 


0x0000) 
0x0000) 
0x0000) 
0x0000) 
= 
0x0000) 
ay. 
0x0000) 
a. 
0x0000) 
x] 
0x0000) 
* i 
0x0000) 
0x0000) 
0x0000) 


/* Invalid op attempts or values */ | 


: /* Detailed Read Error Specifiations */ 


/* READ _U/CERROR_XX is combined with LLD_RE 


as Minor Return Value */ 


| #define 
| #define 
| #define 
| #define 


| #define 
; #define 
: #define 
| #define 


| #define 
| #define 
: #define 
| #define 


i #define 
| #define 
| #define 
| #define 


1LD_READ_CERROR_SO 
1LD_READ_UERROR_SO 
,1LD_READ_CERROR_MO 
,1LD_READ_UERROR_MO 
D_READ_CERROR_S1 
D_READ_UERROR_S1 
D_READ_CERROR_M1 
D_READ_UERROR_M1 
,\LD_READ_CERROR_S2 
,1LD_READ_UERROR_S2 
,1LD_READ_CERROR_M2 
,1LD_READ_UERROR_M2 
D_READ_CERROR_S3 
D_READ_UERROR_S3 
,1LD_READ_CERROR_M3 
,1LD_READ_UERROR_M3 
i /* Previous Operation Flag */ 


| /* LLD_PREV_OP_RESULT is combined with Major Return Value, 


Previous Operation Error except LLD_READ_ERROR */ 


| #define 


LLD_PREV_OP_RESULT 


XSR_RETURN_VALUE (1, 0x000B, 0x0000) 
XSR_RETURN_VALUE (1, 0x0011, 0x0000) 
XSR_RETURN_VALUE (1, 0x0012, 0x0000) 
XSR_RETURN_VALUE (1, 0x0013, 0x0000) 
AD_ERROR 
XSR_RETURN_VALUE (0, 0x0000, 0x0001) 
XSR_RETURN_VALUE (0, 0x0000, 0x0002) 
XSR_RETURN_VALUE (0, 0x0000, 0x0004) 
XSR_RETURN_VALUE (0, 0x0000, 0x0008) 
XSR_RETURN_VALUE (0, 0x0000, 0x0010) 
XSR_RETURN_VALUE (0, 0x0000, 0x0020) 
XSR_RETURN_VALUE (0, 0x0000, 0x0040) 
XSR_RETURN_VALUE (0, 0x0000, 0x0080) 
XSR_RETURN_VALUE (0, 0x0000, 0x0100) 
XSR_RETURN_VALUE (0, 0x0000, 0x0200) 
XSR_RETURN_VALUE (0, 0x0000, 0x0400) 
XSR_RETURN_VALUE (0, 0x0000, 0x0800) 
XSR_RETURN_VALUE (0, 0x0000, 0x1000) 
XSR_RETURN_VALUE (0, 0x0000, 0x2000) 
XSR_RETURN_VALUE (0, 0x0000, 0x4000) 
XSR_RETURN_VALUE (0, 0x0000, 0x8000) 


and means : 


XSR_RETURN_VALUE (0, 0x0000, OxFOFO) 
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BK RK RR KKK KK RRR KK RK KR ROKK KR RK KK RK KK KR RK KK / 


i /* Flags x 


BO [ROR ROR KR OK KK OK KK OK OK OK OK OK OK OK OK OK OK OK OK KK OK OK KK OK OK OK RK OK KK KK / 


| #define LLD_FLAG_ASYNC_OP (1 << 0) /* Write/Erase/Copy */ 
i #define LLD_FLAG_SYNC_OP (0 << 0) /* Write/Erase/Copy */ 
: #define LLD_FLAG_ SYNC_OP_INV (~LLD_FLAG ASYNC_OP) 

i /* Write/Erase/Copy */ 
: #define LLD_FLAG_ECC_ON (1 << 1) 

i #define LLD_FLAG_ECC_OFF (0 << 1) 

: #define LLD_FLAG_ ECC_OFF_INV (~LLD_FLAG ECC_ON) 

| fRRRARRAR EAHA EEAERAHAR EAE SERA EAES AEA RAE EERE AERA EA DARE ARERR RED / 
: /* LLD IO Ctrl Code */ 


BKK RR RK KK KK RR KKK RK RR RK KK KK KK KKK RK KK / 


| /* IOC Code */ 


| #define IOC_SET_SECURE_LT 0x01  /* Set Lock-Tighten *y 
i #define IOC_GET_SECURE_STAT 0x02 /* Get Secure Status xf 
i #define IOC_RESET_NAND_DEV 0x03 /* Reset NAND Device */ 
| #define IOC_SET_BLOCK_LOCK 0x04 /* Block Lock */ 
| /* IOC Return Value */ 

: #define LLD_IOC_SECURE_LT 0x01 /* Lock-Tight * / 
: #define LLD_IOC_SECURE_LS 0x02 /* Locked Status */. 
| #define LLD_IOC_SECURE_US 0x04 /* Unlocked Status */ 
fe Set Device lock-tight */ 

i #define LLD_IOC_SET_SECURE_LT XSR_IOCTL_CODE(XSR_MODULE_LLD, \ 
; IOC_SET_SECURE_LT, \ 


XSR_METHOD_INOUT_DIRECT , \ 

i XSR_ANY_ACCESS) 

| #define LLD_IOC_SET_BLOCK_LOCK XSR_IOCTL_CODE (XSR_MODULE_LLD, \ 

i IOC_SET_BLOCK_LOCK, \ 
XSR_METHOD_INOUT_DIRECT, \ 
XSR_ANY_ACCESS) 


i /* Get Device security status 
: return value 


DEV_LT Device is lock-tighten 

DEV_AL All blocks of device are locked 
i DEV_UL There is an unlocked block */ 
: #define LLD_TOC_GET_SECURE_STAT XSR_IOCTL_CODE (XSR_MODULE_LLD, \ 
: IOC_GET_SECURE_STAT, \ 


XSR_METHOD_INOUT_DIRECT, \ 
XSR_READ_ACCESS) 


| /* Reset Nand Device */ 

| #define LLD_IOC_RESET_NAND_DEV  XSR_IOCTL_CODE(XSR_MODULE_LLD, \ 

i IOC_RESET_NAND_DEV, \ 
XSR_METHOD_INOUT_DIRECT, \ 
XSR_ANY_ACCESS) 


BKK RR RK KK KK RR KK KR RK RR RK KR KR KR KK KK RK KK / 


i /* Data Structures */ 
FOO IO IOC IO I IC III II III II IC I IO I II IO IO III I IO I I IO A I / 
| typedef struct { /* offset size */ 
i UINTS8 nMCode; /* Manufacturer Code 0x00 1 */ 
UINTS8 nDCode; /* Device Code 0x01 1 */ 
UINT16 nNumOfBlks; /* The Number of Blocks 0x02 2 */ 
UINT16 nPgsPerBlk; /* The Number of Pages per Block 0x04 2 */ 
UINT16 nBlksInRsv; /* The Number of Blocks 0x06 2 


in Reserved Block Pool */ 
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UINT8 nSctsPerPg; /* The Number of Sectors per Page 0x08 1 

UINT8 nNumOfPlane; /* The Number of Plane 0x09 1 

UINT8 nMEFlag; /*Multiple Erase Flag Ox0OA 1 
UINT8 nBWidth; /* Device Bus Width ox0c 1 */: 
UINT8 nBadPos; /* BadBlock Information Position 0Ox0E 1 xf i 
UINT8 nLsnPos; /* LSN Position Ox0E 1 wf 
UINTS nEccPos; /* ECC Value Position Ox0F I */ | 
UINT8 aUID[XSR_UID_SIZE]; /* UID 0x10 16, | 
OxFF (absence case of UID) a | 
UINT16 nTrTime; /* Physical Read Operation Time Ox20 2 */ 
UINT16 nTwTime; /* Physical Write Operation Time 0x22 2 xf 
UINT16 nTeTime; /* Physical Erase Operation Time 0x24 2 wf 
UINT16 nTfTime; /* Data Transfer Time Ox26 2 */ | 
} LLDSpec; : 
typedef struct { i 
UINT16 nMEListSbn; /* MEList Semi-physical Block Number xf 
UINT16 nMEListPbn; /* MEList Physical Block Number wf 
} LLDMEList; i 
typedef struct { i 
LLDMEList *pstMEList; /* Pointer to LLDMEList */ | 
UINT16 nNumOfMList; /* Number of Entries of LLDMEList w/t 
UINT16 nBitMapErr; /* Error Bitmap Position of MEList af 
BOOL32 bFlag; /* Valid Flag */ | 


} LLDMEArg; 


[ROK KK KK KK I I I I I A A  / 


/* LLD Function Table Data Structures * / 
[KOK KK KK KK IK IK IK OK I I I I I I A I A A A I A I I A I A OK / 


typedef struct { 


INT32 (*Init) (VOID *pParm) ; 

INT32 (*Open) (UINT32 nDev); 

INT32 (*Close) (UINT32 nDev); 

INT32 (*Read) (UINT32 nDev, UINT32 nPsn, UINT32 nScts, 
UINTS8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag); 

INT32 (*Write) (UINT32 nDev, UINT32 nPsn, UINT32 nScts, 
UINT8 *pMBuf, UINT8 *pSBuf, UINT32 nFlag); 

INT32 (*MRead) (UINT32 nDev, UINT32 nPsn, UINT32 nScts, 
SGL *pstSGL, UINT8 *pSBuf, UINT32 nFlag); 

INT32 (*MWrite) (UINT32 nDev, UINT32 nPsn, UINT32 nScts, 
SGL *pstSGL, UINT8 *pSBuf, UINT32 nFlag, 
UINT32 *pErrPsn) ; 

INT32 (*CopyBack) (UINT32 nDev, CpBkArg *pstCpArg, UINT32 nFlag) ; 

INT32 (*Erase) (UINT32 nDev, UINT32 Pbn, UINT32 nFlag); 

INT32 (*GetDevinfo) (UINT32 nDev, LLDSpec *pstDeviInfo) ; 


INT32 (*ChkInitBadBlk) (UINT32 nDev, UINT32 Pbn); 
INT32 (*FlushOp) (UINT32 nDev); 
INT32 (*SetRWArea) (UINT32 nDev, UINT32 nSUbn, UINT32 nUBlks); 
INT32 (*GetPrevOpData) (UINT32 nDev, UINT8 *pMBuf, 
UINTS8 *pSBuf); 
INT32 (*IOCt1) (UINT32 nDev, UINT32 nCmd, 
UINT8 *pBufI, UINT32 nLenI, 
UINT8 *pBufO, UINT32 nLeno, 
UINT32 *pByteRet) ; 


INT32 (*MErase) (UINT32 nDev, LLDMEArg *pstMEArg, 
UINT32 nFlag); 
INT32 (*EraseVerify) (UINT32 nDev, LLDMEArg *pstMEArg, 
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i UINT32 nFlag); 
: | LowFuncTbl; 


| #endif /* _XSR_LLD_H_ */ 


ll. PAM.h 


| #ifndef _XSR_PAM_H_ 
| #define _XSR_PAM_H_ 


BKK RK RK KKK RK RK RK KKK KR RK KKK RK RK RK KK KR RK KK / 


: /* Definitions of PAM */ 
FRI III ICICI ICICI ICICI ICICI III I II A A A kk / 
: #define NOT_MAPPED OxFFFFFFFF /* Device not mapped 


i in platfomr memory map */ 
i /* ECC Polic 


i y Selection */ 

i #define NO_ECC ) /* No ECC execution * | 

| #define SW_ECC 1 /* ECC execution by SW ae] 

: #define HW_ECC 2 /* ECC execution by HW * / 

/* Lock Scheme Policy Selection */ H 
: #define NO_LOCK_SCHEME 0) /* No Lock Scheme execution */ 
| #define SW_LOCK_SCHEME 1 /* Lock Scheme execution by SW */ | 
i #define HW_LOCK_SCHEME 2 /* Lock Scheme execution by HW */ i 


FOO IO IOC II II II III III II I IOI II IO IO I ICR I IO I I I a IO / 


/* return typedef of PAM _GetPAParm() af 
BKK RK RR KKK KK RR RK KK KK RK KK KR RK KK RK KK KK KK / 
| typedef struct { 
UINT32 nBaseAddr[XSR_MAX_DEV/XSR_MAX_VOL]; : 
/* the base address for accessing NAND device */ | 
UINT16 nEccPol; /* Ecc Execution Section i 
NO_ECC : No Ecc or another type of ECC 
SW_ECC : Ecc Execution by XSR SW 
HW_ECC : Ecc Execution by HW 
(based on Hamming code) *x/ 
UINT16 nLSchemePol; /* Lock Scheme Policy Section 


NO_LOCK_SCHEME No Lock Scheme H 

SW_LOCK_SCHEME iock Scheme Execution | 

by SW i 

HW_LOCK_SCHEME : Lock Scheme Execution | 

by HW i 

(if HW has Lock/Unlock functionality) */ : 

BOOL32 bByteAlign; /* Memory Byte Alignment Problem i 


TRUE32 : Byte Align Problem Free in 
XSR and LLD 
(Memory usage increased) 
FALSE32 : No Action for Byte Align 


Problem ay. 
UINT32 nDevsInVol; /* number of devices in the volume */ i 
VOID *pExInfo; /* For Device Extension. 
For Extra Information of Device, i 
data structure can be mapped. */ i 


i} XsrVolParm; 


BKK RK RRR KK KR RR KKK RK RR KKK KK KK KK KK RR RK KK / 
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/* Exported Function Prototype of PAM */ | 
[KK KK KK KK HK KK OK I IK I IK I I I I OK I I I I A I I OH  / 
#ifdef __ cplusplus 
extern "C" { 

#endif /* __cplusplus */ 


VOID PAM Init (VOID) ; 

VOID *PAM GetPAParm (VOID) ; 

VOID PAM_RegLFT (VOID *pContext) ; 

VOID PAM _Memcpy (VOID *pDst, VOID *pSrc, UINT32 nLen); 


#ifdef ASYNC_MODE 


VOID PAM_InitInt (UINT32 nLogIntId); 
VOID PAM_BindInt (UINT32 nLogIntId); 
VOID PAM _EnableInt (UINT32 nLogIntId); 
VOID PAM DisableInt (UINT32 nLogIntId); 
VOID PAM CleartInt (UINT32 nLogIntId); 


#endif /* ASYNC_MODE */ 


#ifdef _ cplusplus 
} 
#endif /* __cplusplus */ 


_d#endif /* _XSR_PAM_H_ */ 


XSR v1.5.1 Porting Guide 224 


SAMSUNG ONGIT. 


i 
Pena sb lavifed 


Index 


O 
OAM_AcquireSM ...0.. 0. eee eeeeeeeeeeeeeetees 59 
OAM_BindInt......... ccc eeccceceesceceesseeeeeenes 65 
OAM_ ClearInt........ cc ccccccecceccceceesesseeeeeees 71 
OAM_CreateSM.........ccccccecccececeesenseeeeeeees 55 
OAM _DebU8 is csscccsssscsescisessestesesouscoscssubens 54 
OAM_DestroySM .0.0.... ee eceeceeeeeeeeeeeeeees 37 
OAM_DisableInt ............ ccc cccceeseneeeeeeees 69 
OAM_EnableInt ..............ccceccccceesensreeeeeees 67 
OAM. Bie ieccic..cnceisdesessssdaceitesiaeessendencetase¥e 48 
OAM_GetROLockFlag ...0... eee 81 
OAM Get Times scicccvescsasecsacsesessideatsccciteevze 75 
OAM Idle ciscs3 cies Seccsans fh echedssadeeassennts Seeks 80 
OAM InitInt..... 0. ccc eceeceeeesseeeeeenee 63 
OAM. Mall: cs. ccscscSesdsseascecdesevesdsccesiecteastse 47 
OAM_Meme mp occ eeeeereeeeeeeeeeees 52 
OAM _Memcp)....... eee eeeeeeeseeeeeeeeeees 49 
OAM_ Meet ...........ccecccceccececeessssseeeeeeeeees 51 
OAM Pa2V a eissscscctisbcessthicncebesssnesitboundbecacs 78 
OAM_ReleaseSM...............cc:cccccccessessreseeees 61 
OAM ResetTimet ..............ccccceccseceeeeseeeeees 73 
OAM_WaitNMScec..........ccccccccceceesesseeeeeees 77 
P 
PAM_ Bind Int .....0.00 cece cceeceeeseceeeseeeees 172 


PAM ‘Clearlnt :.ccsc.sccssncis. cdcaassiaeseesneess 178 
PAM_DisableInt ............ccccccceesseceeeeseeees 176 
PAM EnablelInt ........ ee eeeeeeeeeeeee 174 
PAM_GetPAParm...............ccccecsecceeeeeseeeee 162 
PAM Titits a scieci aienctciawe nunca: 161 
PAM Tnitlint x. cssccissccissctisetsiieenticcssiesciieess 170 
PAM Memcpy’..scvscstssissatestsenitessestesesiens 180 
PAM RES LET cca tecsencietcteSeeeSarivces 166 
Xx 
XXX_ChkInitBadBlk ......... eee eeeeeeeee 143 
DEX X, (CIOSEs sieesci cseisvisescccVeessnnssbeckeses sacseese 90 
XXX_CopyBack 0... eee eeeeeeeeeeeeeeeees 135 
MXX Erase vecciccsssssciesdeelesisieahecdesctestonss 107 
XXX_Erase Verify... eeseeeesesseeeeeseeseeees 132 
XXX_FlushOp ...0.... ee ceceeseesceeseeeseeseeeeeeeees 156 
XXX_GetDevInfo..0..... cece cecsseeceeneeee 92 
XXX_GetPrevOpData ....... eee 153 
HK Tits. 23cheessss hase sortie hesceieadeed esas 85 
RX TOC ec seseecviteeckatedoncisalecuisevetioviis 147 
XXX MBAS es. cccvidvsieetecedieiysissuseserechee te 126 
XX MRE vives ey itrocuarteseeebaalicestiecyedveces 110 
KX XM Waite irvecccvisssceccecleiissssnsesivecsaveivorts 118 
XXX JOP CMs seviis tins Suisse etien 87 
RX REA cseesnnsitsstusshehs Reiaaliciousive teers bus 97 
XXX_SetRWASEA........ cc ceeccecsseceeeeesteeeeees 145 
RIK WS 2 ieivocieitectush db. eieeeceuseveceeeetls 102 


XSR v1.5.1 Porting Guide 225 


